Custom Hairstyles

Custom Hairstyles

← Custom Skin Textures

MCA tints hairstyle textures at runtime using the villager's hair color. One hairstyle can therefore work with black, brown, blond, red, dyed, or rainbow hair without needing separate PNG files for each color.

Quick setup

For one simple female hairstyle, your pack can look like this:

assets/example/skins/hair/female/my_hair.png
data/example/skins/hair_styles/female.json

The PNG belongs in the resource pack. The JSON belongs in the datapack.

Then add this to data/example/skins/hair_styles/female.json:

{
  "example:skins/hair/female/my_hair.png": {
    "gender": "female",
    "base": "example:skins/hair/female/my_hair.png"
  }
}

That is enough for a normal one-layer hairstyle.

Making the texture

Hair should normally be grayscale because MCA multiplies the villager's hair color over it.

• White keeps the selected hair color bright.
• Light gray makes it a little darker.
• Dark gray makes it much darker.
• Pure black stays black no matter which hair color is selected.

For most styles, start fairly bright and use gray only where you want shadows or darker strands.

The Skin Editor page shows a useful before and after example:

As with clothing, the texture should contain only the hair. Remove the face, skin, and clothing.

Hair style JSON

Hair style files go under:

data/[yourNamespace]/skins/hair_styles/

The file is a JSON object. Each key is a unique style identifier, and its value describes which texture layers make up that style.

Example:

{
  "example:styles/short_hair": {
    "gender": "neutral",
    "chance": 1.0,
    "base": "example:skins/hair/short_hair.png"
  }
}

gender

Valid values are female, male, and neutral.

If gender is left out, the style defaults to neutral unless MCA can infer a legacy gender from the file or identifier.

For simple packs, setting it explicitly is easiest to understand.

chance

chance controls the relative weight when MCA randomly chooses a hairstyle. The default is 1.0.

For example, a style with 0.25 is picked less often than styles left at 1.0.

Fixed-color overlays

If a hairstyle needs something that should not be tinted with the hair color, add another texture with _overlay before .png.

assets/example/skins/hair/female/my_hair.png
assets/example/skins/hair/female/my_hair_overlay.png

The normal PNG is tinted as hair. The overlay is drawn afterward with its original colors.

This is useful for bows, clips, flowers, beads, hats, or other accessories.

You do not need to reference the overlay separately in the style JSON. MCA looks for it automatically.

Layered hairstyles

A hairstyle can be made from several separate textures. The available parts are:

Field	Purpose
base	Main hair layer
bangs	Bangs or fringe
back	Hair rendered behind the main layers
front	Additional front hair
extra	Extra detail layer

You only need the layers your hairstyle actually uses.

Example:

{
  "example:styles/long_hair": {
    "gender": "female",
    "base": "example:skins/layered_hair/base/long.png",
    "bangs": "example:skins/layered_hair/bangs/side.png",
    "back": "example:skins/layered_hair/back/long.png",
    "front": "example:skins/layered_hair/front/strands.png"
  }
}

MCA renders layered hair in this order:

back -> base -> bangs -> front -> extra

Each referenced PNG is tinted with the same hair color. Each one can also have its own automatic _overlay.png if it needs fixed-color details.

Common mistakes

• Do not leave a face or skin-colored pixels in a hair texture. They will be tinted as hair.
• Avoid making the entire hairstyle very dark. Hair tint is multiplied over the texture, so black pixels cannot become blond or bright dyed colors.
• Make sure every base, bangs, back, front, or extra identifier points to a real PNG in the resource pack.
• Use _overlay.png for accessories that should keep their original colors.
• Remember that hairstyles need both the resource pack and datapack sides installed.

See Skin Editor if you want to create, clean up, preview, and publish hairstyles from inside MCA.