Animations
On this page6 sections
AdvancedNametags has two kinds of animation. They mix freely: a line can move and change colour.
| What changes | How it is sent | Where you write it | |
|---|---|---|---|
| Movement | position, size, rotation, opacity | a keyframe every few ticks; the client animates every frame in between | motion, transition, reactions |
| Text effects | the colour of every letter | one text frame every text-effect-interval ticks | tags in the text: <wave>, <pulse>... |
Movement is the "new technology" part: Minecraft's display entities can interpolate their transformation on their own, so the plugin only says where the line must be in N ticks and the client glides there at your monitor's frame rate (60, 144, 240 fps). That is why it looks fluid and costs almost nothing.
1. Motions — movement that loops
Put motion on a template (the whole nametag moves as one object) or on a line (only
that line moves).
templates:
vip:
motion: float # the whole nametag floats
lines:
- "<badge:vip> {player}"
- text: "<gray>Supporter"
motion: sway # this line also tilts, on top of the floatBuilt-in motions
| Motion | What it does | amount means | Default amount | One cycle |
|---|---|---|---|---|
float | drifts up and down | blocks | 0.05 | 3 s |
breathe | grows and shrinks | relative size (0.04 = ±4 %) | 0.04 | 3 s |
sway | tilts side to side | degrees | 3 | 4 s |
swing | turns left and right | degrees | 14 | 4 s |
spin | turns around continuously | – | – | 5 s |
orbit | circles around the head | radius in blocks | 0.35 | 5 s |
Options are written after a colon or a space: speed (1 = normal, 2 = twice as fast, 0.5 =
half; 0.05–5) and amount (-45 to 45). bob, pulse, wiggle and rotate are aliases of
float, breathe, sway and spin (the names UnlimitedNametags uses). Your own keyframe motions
take speed only.
motion: "spin speed=0.6" # options after a space or a colon
# motion: "float:amount=0.08"
# motion: "float:amount=0.03, breathe:amount=0.02" # combine several with commas
# motion: "spin speed=0.6, float:amount=0.04" # a turning, floating crownspin is meant for item and block rows (a turning crown or diamond). On text it shows the
back of the text half of the time; use swing for text instead.
Your own motion with keyframes
In animations.yml, under motions:. A keyframe says "at this tick, the line is like this";
between keyframes the line moves smoothly.
motions:
heartbeat:
length: 30 # the loop lasts 30 ticks (1.5 s)
keyframes:
0: {scale: 1}
4: {scale: 1.12, ease: out} # quick beat
8: {scale: 1, ease: in}
12: {scale: 1.08, ease: out} # second, smaller beat
17: {scale: 1, ease: in} # rest until tick 30, then loopUse it by name anywhere a motion goes: motion: heartbeat, motion: "heartbeat speed=1.5".
Properties
| Property | Unit | Example |
|---|---|---|
x, y, z | blocks (y = up) | y: 0.1 |
scale | size factor, 1 = normal | scale: 1.2 |
scale-x, scale-y | stretch one way only | scale-y: 0.8 (squash) |
yaw | turn left/right, degrees | yaw: 25 |
pitch | tip forward/back, degrees | pitch: -10 |
roll | tilt sideways, degrees | roll: 8 |
opacity | 0 (invisible) to 1 | opacity: 0.5 |
ease | how this keyframe is reached | ease: in-out |
A property left out of a keyframe keeps its value from the previous one, so you only write what changes. After the last keyframe the loop glides back to the first.
Easing curves — how the movement accelerates towards a keyframe:
ease | Feels like | Good for |
|---|---|---|
linear (default) | constant speed | spinning, scrolling |
in | starts slow, ends fast | falling, leaving |
out | starts fast, ends slow | arriving, a punch |
in-out | slow – fast – slow | anything that swings or floats |
back | overshoots a little and settles | landing, popping in |
step | jumps instantly | teleporting a line while it is invisible |
Tips
- Keep turns under 180° between two keyframes (the client always takes the short way round).
For a full turn use several keyframes:
0: {yaw: 0},10: {yaw: 120},20: {yaw: 240},30: {yaw: 360}. - Small amounts look premium:
y: 0.05,roll: 3,scale: 1.05. Big ones look cheap fast. lengthis in ticks: 20 ticks = 1 second.
Shortcuts
A motion can also be a name for a combination you use often:
motions:
gentle: "float:amount=0.03, breathe:amount=0.02"2. Transitions — when a line changes its text
A line with frames shows several texts in turn. The transition is how one text leaves and
the next arrives.
lines:
- frames:
- "<gold>play.myserver.net"
- "<aqua>discord.gg/myserver"
frame-ticks: 80 # switch every 4 seconds
transition: roll # roll like a counter (default: animations.transition in config.yml)| Built-in | |
|---|---|
flip (default) | turns edge-on, swaps the text, turns back |
roll | the old text rolls up and away, the new one rolls in from below |
pop | shrinks to nothing and pops back with a bounce |
fade | fades out and in |
none | swaps instantly |
Add :ticks=N to change the duration (2–100, default 10): transition: "flip:ticks=16". Your
own transitions take no options.
transition on a line plays on every change of that line, not only between frames. On a line
like "<white>{health} <icon:heart>" it rolls each time the health changes — a live counter.
Your own transition
Under transitions: in animations.yml. The text is swapped exactly halfway through
length, so make the line invisible (or edge-on) at that moment. It starts and ends at rest, so
you can leave out the first and last keyframes.
transitions:
slide:
length: 12
keyframes:
6: {x: -0.6, opacity: 0, ease: in} # leaves to the left, fading (text swaps at 6)
7: {x: 0.6, opacity: 0, ease: step} # jumps to the right while invisible
12: {x: 0, opacity: 1, ease: out} # comes in from the right3. Reactions — once, on an event
Event (trigger) | When |
|---|---|
damage | the player takes damage (more than 0 after armour) |
level-up | the player gains a level |
kill | the player kills another player |
chat | the player sends a chat message (not cancelled) |
Defaults for everyone are in config.yml (animations.reactions); a template replaces the ones
it lists (the other events keep the global reaction):
templates:
founder:
reactions: {damage: wobble, chat: bounce, level-up: celebrate}| Built-in | Duration | |
|---|---|---|
pop | 8 ticks | grows from nothing |
fade | 8 | fades in |
bounce | 12 | swells and settles |
shake | 10 | wobbles like a hit |
jump | 12 | hops up |
spin | 16 | turns around once |
none | turns the reaction off |
:ticks=N changes the duration (2–100): damage: "shake:ticks=6". It only works on the built-in
reactions.
Your own reactions go under reactions: in animations.yml, with the same keyframes. Like
transitions, they start and end at rest:
reactions:
celebrate:
length: 24
keyframes:
6: {y: 0.3, yaw: 120, ease: out}
12: {y: 0.35, yaw: 240}
18: {y: 0, yaw: 360, ease: in}Other plugins can play any reaction: /nametag react <player> celebrate or
AdvancedNametagsApi.get().react(player, "celebrate") (a minigame point, a crate opening...).
Appear effect: animations.appear in config.yml (pop, fade, none, or any reaction)
plays when a nametag comes into view.
4. Text effects — colour
Wrap text in an effect tag:
- "<wave>{player}</wave>" # rainbow wave
- "<wave:#ff5f6d:#ffc371>{player}</wave>" # colours flowing along the text
- "<pulse:color=#ff2a2a>● LIVE</pulse>" # breathing brightness
- "<shine:color=#c86bfa:highlight=white>FOUNDER</shine>" # a light sweeping across
- "<anim:rainbow>{player}</anim>" # animated rainbow
- "<anim>{player}</anim>" # the template's `animation`, or animations.text-effect<anim:name> works for every effect and preset. The short form <name> works too, except where
it would replace a standard MiniMessage tag: <rainbow> and <gradient> stay MiniMessage's
static ones, so write <anim:rainbow> for the animated rainbow.
| Effect | Options |
|---|---|
wave | colors (comma separated; none = rainbow), wavelength (characters per cycle), saturation, brightness |
rainbow | wavelength, saturation, brightness |
pulse | color or colors, min and max brightness (0–1), spread (offset per character) |
shine | color or colors (the base), highlight, width (characters), pause (seconds between sweeps) |
Every effect also takes speed (above 0, up to 50). In a tag, options are separated by : and
bare colours are the colors: <wave:speed=2:#f00:#00f>. Defaults: pulse is #FF55FF between
0.35 and 1 brightness; shine is #B0B0B0 with a white, 3-character highlight every 1.5 seconds;
wave spans the text (at least 6 characters) and loops every 2 seconds.
Presets
Save an effect with its options under presets: in animations.yml and use it as its own tag:
presets:
royal:
type: shine
color: '#ffcc33'
highlight: '#fff6d5'
width: 3
pause: 2- "<royal>{player}</royal>"Bundled: gold-pulse, ocean, sunset, toxic, silver, royal, founder-shine. Bundled
motions, reactions, transitions and presets stay available even if you delete them from your
animations.yml; define the same name to replace one. Preset names cannot be standard MiniMessage
tags (gold, rainbow...).
/nametag animations <spec> shows any effect on your own name for a few seconds (press F5),
e.g. /nametag animations wave:#ff5f6d:#ffc371.
Developers can add new effect types: AdvancedNametagsApi.get().registerAnimation(...)
(see integrations).
5. Recipes
# A crown turning above the head
- type: item
item: golden_helmet
motion: "spin speed=0.6, float:amount=0.04"
glow: "#FFD24A"
scale: 0.42
# A LIVE line that beats
- frames: ["<pulse:color=#FF2A2A>●</pulse> <white>LIVE NOW", "<gray>twitch.tv/<white>{player}"]
frame-ticks: 70
transition: pop
motion: heartbeat
# A health counter that rolls on every change
- text: "<white>{health} <icon:heart>"
transition: roll
refresh-ticks: 10
# A sign swinging from a nail: put `motion: pendulum` on the template itself
# Two teams swapping with a vortex
- frames: ["<red><b>⚔ RED", "<blue><b>⚔ BLUE"]
frame-ticks: 60
transition: vortexThe bundled templates/showcase.yml has complete designs combining all of the above; see
presets.
6. Performance
- A looping motion costs one small packet per line every
animations.keyframe-ticks(5 ticks) near the viewer, up to three times fewer atperformance.animation-distance, and nothing beyond it. Reactions and transitions use 2-tick keyframes only while they play. - Text effects cost one text packet per frame and are the expensive kind: prefer movement, and use effects on short texts (a name, a word).
performance.max-animation-bandwidth(KiB/s per player) caps everything that changes over time, placeholder updates included; in a crowd the farthest nametags slow down first, and a new value waits at most 2 seconds./nametag debugshows the live numbers.- A badge is heavy (about 200 bytes per 8×8 tile), so a line with a badge and a fast-changing
placeholder (
{ping}) is re-sent whole on every change. Put fast values on their own line when you can.