Animate a skin
Make a skin change colour: pick one of the forty-one presets, write your own, and see it move in game.
An animation makes a skin's colour move. You end with a skin that shifts colour in game, using one of the forty-one presets that ship or one you write. The trim, the name, the lore and the durability never change with it.
Before you start#
You have a skin, see Create and edit skins. Presets and your own animations live in animations.yml.
Steps#
Pick a preset
Every shipped preset is named after a skin: rainbow, inferno, galaxy, phoenix and so on. The full list is in the technical details below.
Name it on the skin
In skins.yml:
skins:
inferno:
animation: infernoReload
Run /armorskinsadmin reload.
Wear it
Put the skin on a piece, see Your first skin.
Check that it works#
The colour of the piece moves on its own, on your body and for other players. A skin with no animation stays a still colour. animation: rainbow with no matching preset falls back to the type with its defaults, which is why rainbow works before anybody has opened animations.yml.
animation: sparkle with no such preset and no such type logs which presets and types exist, and the skin loads as a still colour. The same happens to an entry in animations.yml whose type is unknown or missing.
Going further#
Write your own preset#
Add an entry under animations: in animations.yml, then name it from a skin:
animations:
inferno:
type: frames
interval: 0.1
colors: ['#3a0000', '#c81d00', '#ff7a00', '#ffd000', '#ff7a00', '#c81d00']
options:
steps: '6'| Key | What it is |
|---|---|
type | rainbow, pulse, frames, wave, sweep, bloom, flicker, or a type another plugin registered. |
interval | Seconds between frames. Never below one tick. |
colors | Hex colours the type works with. What they mean depends on the type. |
options | Free-form per-type values, written as text. |
Make it travel across the set#
wave, sweep, bloom and flicker know which piece they are painting, so the animation moves across the four pieces instead of playing the same frame on all of them. They only show on a full set.
Turn the metal of the trim#
Any type can also cycle the trim's material with the materials option. See the technical details.
Everyone sees the same frame#
The frame comes from the server clock, so two players wearing rainbow show the same colour at the same instant. An animation costs one repeating task per animated piece worn, and nothing for a still skin.
Add a type in code#
Another plugin can register an animation type and use it from YAML. See API.
The seven types and their options
The seven types
rainbow#
Walks the hue circle. Ignores colors and the skin's own colour.
| Option | Default | Effect |
|---|---|---|
step | 10 | Degrees of hue per frame. Lower is slower and smoother. |
saturation | 1.0 | 0 – 1. Lower washes the colours out. |
brightness | 1.0 | 0 – 1. Lower darkens them. |
pulse#
Breathes from a rest colour to a peak and back.
| Option | Default | Effect |
|---|---|---|
length | 40 | Frames for a full there-and-back. Minimum 2. |
The first entry in colors is the rest colour; with none, the skin's own color is used, and with
neither, black. The second entry is the peak; with none, white.
frames#
Cycles through colors in order.
| Option | Default | Effect |
|---|---|---|
smooth | true | Blends between neighbouring colours instead of jumping. |
steps | 10 | Frames spent blending from one colour to the next. Only read when smooth is on. |
With smooth: 'false' each frame is one colour from the list. With one colour it holds that colour;
with none it leaves the skin's own colour alone.
The four that read the body
wave, sweep, bloom and flicker know which piece they are painting, so the animation travels
across the set instead of playing the same frame on all four. A skin that fits one piece looks the
same as it always did; a full set is where they show.
| Type | What it does | Options |
|---|---|---|
wave | The colour rolls up or down the body, one piece behind the next. | length (40 frames), spread (0.25), direction (up / down) |
sweep | A band of light crosses the body once per pass, then the set rests dark. | length (40), width (0.45), hold (0), direction |
bloom | A pulse opens out of one piece; its neighbours follow a beat later. | origin (chestplate), length (40), delay (6), width (14) |
flicker | Sparks catch one piece at a time. sync: true flashes all four together. | chance (0.18), hold (2), sync (false) |
pulse, sweep, bloom and flicker read the first colour as the resting one and the second as
the one they reach for; frames and wave cycle through all of them.
Turning the metal in a trim
Any type can also cycle the trim's material while the leather keeps its own animation. The pattern never changes — only the metal in it.
prismatic:
type: sweep
colors: ['#1b1035', '#c77dff']
options:
materials: 'amethyst,diamond,gold,netherite'
trim-hold: 10
trim-spread: 3| Option | Default | What it does |
|---|---|---|
materials | — | The trim materials it turns through, in order. Without it nothing about the trim moves. |
trim-hold | 10 | Frames each material is held for. |
trim-spread | 0 | Frames of offset between one piece and the next, so the metal reaches the helmet after the boots. |
It needs a skin with a trim-pattern and a trim-material. On a skin without one the leather still
animates, no trim appears, and nothing is reported: a trim cycle on a skin that has no trim is a
setting with nothing to do, not an error.
The forty-one presets
The forty-one presets
| Preset | Type | Interval | Options | Colours |
|---|---|---|---|---|
rainbow | rainbow | 0.1 s | step: 8 | — |
rainbow_slow | rainbow | 0.25 s | step: 4 | — |
pastel | rainbow | 0.15 s | step: 6, saturation: 0.45 | — |
heartbeat | pulse | 0.05 s | length: 24 | #7a0010 → #ff2a4d |
toxic | pulse | 0.1 s | length: 30 | #0b1f0b → #5dff3a |
ember | pulse | 0.1 s | length: 40 | #2b0a00 → #ff5a00 |
shogun | pulse | 0.08 s | length: 32 | #1a0000 → #c8102e |
bloodmoon | pulse | 0.1 s | length: 36 | #2a0000 → #a3001b |
inferno | frames | 0.1 s | steps: 6 | six reds and oranges |
ocean | frames | 0.15 s | steps: 8 | six blues |
galaxy | frames | 0.15 s | steps: 8 | five purples and pinks |
aurora | frames | 0.2 s | steps: 10 | five greens, cyans and violets |
voltage | frames | 0.08 s | smooth: false | four blues and white, switched hard |
tempest | frames | 0.12 s | steps: 8 | five greys and pale blues |
sakura | frames | 0.2 s | steps: 10 | five pinks |
dragonfire | frames | 0.1 s | steps: 6 | five embers |
void_dragon | frames | 0.18 s | steps: 8 | five violets |
frostbite | frames | 0.2 s | steps: 10 | four ice blues |
neon | frames | 0.1 s | steps: 6 | four neons |
verdant | frames | 0.25 s | steps: 10 | five greens |
celestial | frames | 0.2 s | steps: 10 | four golds |
thunderlord | flicker | 0.05 s | chance: 0.22, hold: 2 | #0b1030 → #dff1ff |
spectre | flicker | 0.08 s | chance: 0.25, hold: 3 | #123a3a → #b8fff6 |
warden | flicker | 0.1 s | chance: 0.12, hold: 4, sync: true | #06171a → #1fd6c9 |
tidecaller | wave | 0.1 s | length: 40, spread: 0.22 | five colours, #04263b → #8fe3ff |
glacier | wave | 0.1 s | length: 50, spread: 0.3 | four colours, #2a5b7a → #ffffff |
nebula | wave | 0.12 s | length: 60, spread: 0.25 | five colours, #12002b → #ff6bd6 |
venom | wave | 0.08 s | length: 36, spread: 0.28 | five colours, #0b1f0b → #c9ff8f |
blossomfall | wave | 0.15 s | length: 50, spread: 0.25, direction: down | four colours, #fff0f5 → #ffd6e6 |
starfall | sweep | 0.05 s | length: 34, width: 0.4, hold: 12, direction: down | #1b1b3a → #fff6cf |
solarflare | sweep | 0.05 s | length: 26, width: 0.35, hold: 6 | #4a1400 → #ffe680 |
wildfire | sweep | 0.04 s | length: 20, width: 0.5 | #2b0a00 → #ff8c1a |
phoenix | bloom | 0.05 s | origin: chestplate, length: 50, delay: 6, width: 16 | #3a0a00 → #ffb347 |
magmacore | bloom | 0.08 s | origin: chestplate, length: 60, delay: 8, width: 20 | #1a0500 → #ff5714 |
abyss | bloom | 0.1 s | origin: boots, length: 70, delay: 9, width: 24 | #01040f → #2b6cb0 |
eclipse | bloom | 0.08 s | origin: helmet, length: 60, delay: 7, width: 18 | #0a0a0a → #ffd700 |
midas | pulse | 0.1 s | length: 40, materials: gold,copper,quartz, trim-hold: 12 | #7a5200 → #ffd76a |
prismatic | rainbow | 0.08 s | step: 7, materials: amethyst,diamond,emerald,gold,lapis,copper,redstone,quartz, trim-hold: 8, trim-spread: 2 | — |
runeforged | pulse | 0.08 s | length: 30, materials: netherite,redstone,copper, trim-hold: 10, trim-spread: 3 | #1a0505 → #ff3b30 |
chrome | sweep | 0.05 s | length: 30, width: 0.3, hold: 8, materials: iron,quartz,diamond, trim-hold: 10, trim-spread: 3 | #8f9aa6 → #ffffff |
arcane | wave | 0.12 s | length: 45, spread: 0.3, materials: amethyst,lapis,diamond, trim-hold: 14, trim-spread: 4 | four colours, #1b0a3d → #c77dff |
Every shipped skin points at the preset of the same name.
How frames stay in step, and what it costs
Everyone is on the same frame
The frame number comes from the server clock, not from a counter started when the piece was equipped:
frame = floor(currentTimeMillis / 50 / intervalTicks)Two players wearing rainbow, one for an hour and one for a second, show the same colour at the same
instant. Timers still run per player — that is what Folia requires — but the clock they read is
shared.
What it costs
One repeating task per animated piece worn, and nothing at all for a still skin. A frame copies a protocol stack the plugin already holds, writes one colour component on it and re-sends that slot; a frame whose colour has not changed sends no packet. The task stops itself the moment the piece comes off, the skin changes, or the wearer leaves.
animation: sparkle with no such preset and no such type logs which presets and which types exist,
and the skin loads as a still colour. The same happens to an entry in animations.yml whose type
is unknown or missing.
Something missing on this page? Tell us on Discord