Datapack Codex

NPC skins

How Minecraft skins are stored as signed texture data, how to generate that data for any image with MineSkin, and how to apply it to Citizens NPCs (a server plugin) as well as to datapack-native NPCs — the minecraft:mannequin entity and player heads.

📌 Scope note

Citizens is a server plugin (Spigot/Paper), not a data pack — its /npc commands only exist on a server running the plugin. The skin data (texture value + signature), however, is the same everywhere, so the same MineSkin output drives a Citizens NPC, a datapack mannequin, or a player_head. Where a step is plugin-only vs. vanilla/datapack is called out below.

On this page

How a Minecraft skin is stored

A skin is not an image attached to an entity — it is a profile property named textures, carried by any player-shaped thing:

So "giving an NPC a custom skin" always reduces to obtaining a value + signature pair and putting it where that NPC reads its profile. MineSkin exists to produce that pair from any image.

Generating signed skins with MineSkin

MineSkin signs skins for you: upload a skin PNG (or point it at an existing skin/URL) and it returns a signed texture — the value, the signature, a textures.minecraft.net URL, and a UUID.

💡 Skip the upload — use the gallery

The MineSkin skins gallery is a large, browsable repository of already-signed skins. For a lot of NPCs you never need to make your own image: search/scroll the gallery, open a skin, and copy its ready-made URL (for Citizens --url) or its value + signature (for a mannequin/head or Citizens -t). Each gallery entry is already signed, so it drops straight into any of the steps below.

  1. Open mineskin.org, upload your skin image (or pick one from the gallery), and choose the model (classic / slim).
  2. Copy the outputs you need: the URL (easiest for Citizens' --url), or the value + signature (for raw application to Citizens -t, mannequins, or heads).
💡 Tip

MineSkin also has an API — POST an image and store the returned data.texture.value / data.texture.signature in a config, so a plugin or generator can set skins programmatically instead of by hand.

Applying a skin to a Citizens NPC plugin

Select the NPC (/npc select or look at it), then use one of the /npc skin forms. Easiest for a MineSkin custom skin is --url; Citizens signs and caches it for you:

# From a player's account skin
/npc skin Notch

# Always track that player's *latest* skin (lowercase L)
/npc skin Notch -l

# From an image or texture URL (MineSkin output) — recommended for custom skins
/npc skin --url https://textures.minecraft.net/texture/<hash>

# Raw signed blob (developer/console tool): uuid, value, signature
/npc skin -t <uuid> <value> <signature>
📌 Note

Only player-type NPCs render a skin. Citizens stores the skin in the NPC's data so it persists across restarts; changing it re-signs/re-caches. If a skin "won't change", it's usually a stale cache — re-run with --url or restart to clear it.

Applying a skin to a datapack NPC (mannequin / head)

For vanilla, datapack-native NPCs there is no plugin — you put the same MineSkin value/signature into the minecraft:profile profile property. This works for the minecraft:mannequin entity 1.21.9+ and for player_head items:

# A mannequin wearing a MineSkin custom skin
/summon minecraft:mannequin ~ ~ ~ {profile:{properties:[
  {name:"textures", value:"<base64 value from MineSkin>", signature:"<signature>"}
]}}

# A player head with the same skin (data-component form)
/give @s minecraft:player_head[profile={properties:[
  {name:"textures", value:"<value>", signature:"<signature>"}
]}]

If you just want an existing account's skin (not a custom image), the short form profile:{name:"Notch"} resolves it — no MineSkin needed. MineSkin is for custom images that aren't tied to a real account.

Gotchas

Sources