Templates
On this page7 sections
A template is a nametag design: its lines, style and movement. Templates live in
nametags.yml and in every .yml file inside templates/ (the plugin ships
templates/ranks.yml and templates/showcase.yml). All files share one list, so ids must be
unique.
Who gets which template
Every player gets the highest priority template they qualify for. A player qualifies when:
- they have its permission (
advancednametags.template.<id>unlesspermissionsays otherwise), or - they are in one of its
groups: the plugin checks the permissiongroup.<name>, which LuckPerms grants for inherited groups too (other permission plugins work if they grant it), or - it has
permission: noneand nogroups: everyone qualifies (your default template).
templates:
admin:
priority: 175
groups: [admin] # LuckPerms group
lines: ["<badge:admin> <red>{player}"]
event-winner:
priority: 300 # wins over every rank while they have the permission
permission: myserver.winner
lines: ["<gold>🏆 {player}"]
default:
priority: 0
permission: none
lines: ["<badge>{player}"]Template permissions are declared default: false, so operators do not get every template.
Without LuckPerms, permission changes are picked up every updates.permission-check-ticks; with
LuckPerms they apply instantly.
Other ways a player ends up with a template:
- They pick it (if
menu.styles: true): players who qualify for several templates choose one in/nametagor with/nametag style <id>. Their pick only applies while they still qualify. - An admin forces it:
/nametag set <player> template <id>(ignores permissions andworlds;template autoundoes it). A forced template wins over everything else, then the player's own pick, then the highest priority. - A world limit:
worlds: [world_nether]makes a template apply only in those worlds.
/nametag info <player> shows the template a player has, their lines and any customisation.
Template options
| Option | Example | |
|---|---|---|
priority | higher wins | 100 |
permission | who qualifies (none = everyone) | myserver.vip |
groups | LuckPerms groups that qualify | [vip, vipplus] |
worlds | only apply in these worlds | [world_nether] |
lines | the lines, top to bottom | see below |
motion | looping movement of the whole nametag | float |
reactions | replace the global reaction of the events listed (others keep the global one) | {damage: wobble} |
animation | text effect of a bare <anim> tag | ocean |
offset | extra height in blocks | 0.2 |
refresh-ticks | placeholder refresh for every line | 40 |
| style options | apply to every line (see below) | scale: 0.9 |
Lines
A line is a string, or a section with options:
lines:
- "<badge:vip> {player}" # the short form
- text: "<gray>{health} <icon:heart>" # the long form
scale: 0.8
refresh-ticks: 10
transition: roll
- frames: ["<gold>play.myserver.net", "<aqua>discord.gg/myserver"]
frame-ticks: 80
- text: "<gray><i>AFK"
show-if: "%essentials_afk% == yes"
- type: item
item: diamond
motion: spin| Line option | |
|---|---|
text | the text (everything you can put in it) |
frames + frame-ticks | several texts shown in turn, switching every N ticks (default 60); on item rows, several items |
transition | how the line changes text (list); on a line it plays on every change |
motion | looping movement of just this line |
offset | [x, y, z] in blocks, or a number to move it up |
show-if | only show the line when every condition holds (conditions) |
refresh-ticks | placeholder and condition refresh for this line |
hide-if-empty | collapse the line when it renders to nothing (default true) |
type: item / type: block | a floating item or block (options) |
| style options | override the template and config.yml |
Lines are stacked from the bottom: the last line sits right above the head.
Players with custom lines (/nametag set <player> line, the editor) keep the template's look for
each position, but their text replaces the template's text, frames and show-if.
Every option with its type, default and range: configuration reference.
Style options
They can be set in config.yml (display, for everyone), on a template (all its lines) or on a
line. The most specific one wins.
| Option | Values |
|---|---|
scale | size, 1.0 = vanilla |
background | none (no box), default (vanilla box), #AARRGGBB, rainbow, or colours to blend through: "#60FF3B6B, #603A86FF :20" (ticks per colour) |
shadow | true, false, or a colour for a coloured (neon) shadow: "#C0FF00FF" (#RRGGBB is drawn at 75 % opacity) |
see-through | visible through walls, like vanilla (false by default: it is a free wallhack) |
opacity | 26–255 |
billboard | center (faces the camera), vertical (stays upright), horizontal, fixed |
alignment | center, left, right (for multi-row lines) |
brightness | 0–15, or -1 for world light |
line-width | pixels before wrapping |
Colours with alpha are #AARRGGBB (alpha first, like Minecraft): #80000000 is half-transparent
black, #00000000 fully transparent.
Organising your files
- Keep your own designs in
nametags.yml, or split them into files undertemplates/(templates/staff.yml,templates/events.yml...). Each file has atemplates:section. Files are readnametags.ymlfirst, thentemplates/alphabetically; an id defined twice keeps the first one. Ids may usea-z,0-9,_and-. - Delete or empty
templates/ranks.ymlandtemplates/showcase.ymlif you do not want them; they are only re-created when the wholetemplates/folder is missing. /nametag reloadreloads everything and reports each problem with its file and path, e.g.templates/ranks.yml → templates.vip.motion: unknown motion 'flaot'.
Designing in game
/nametag edit <player>opens the editor: template, lines, scale, height, background, badge.- Click Copy as YAML: the design is put in chat; click it to copy, paste it under
templates:and give it apriorityandgroups. /nametag try <template>shows any template on yourself for 10 seconds (press F5).
Players without a design
Keep a template with permission: none (the bundled default) to control what everyone else
sees. If there is none, the plugin adds a built-in default that shows just the name.