Custom Eye Textures

Custom Eye Textures

Warning

This eye texture format is not released yet. This page documents the upcoming format so resource pack authors can prepare for it. Details may still change before release.

MCA can load custom villager eyes from resource packs. New eye textures can mark which pixels keep their original color and which pixels should use the villager's eye color.

Old eye textures without these markers are still supported, so existing resource packs do not need to be converted.

Quick setup

For most resource packs, setup is only a few steps:

1. Copy an existing marked eye texture or download the 64x64 example template.
2. Put it at assets/[yourNamespace]/skins/face/normal/my_eye.png.
3. Paint fixed pixels with alpha 253 and tintable iris pixels with alpha 254.
4. Add the texture to assets/[yourNamespace]/eyes/normal.json.
5. Reload resource packs with F3 + T or restart the game.

That is enough for a normal custom eye. You do not need a datapack, separate textures for each eye color, or tone_overrides.

File structure

Eyes only need a resource pack. A simple pack can look like this:

assets/example/eyes/normal.json
assets/example/skins/face/normal/my_eye.png

example is your resource pack namespace.

The eye PNG is a normal 64x64 RGBA texture. Add it to assets/example/eyes/normal.json so MCA can select it:

{
  "replace": false,
  "textures": [
    "example:skins/face/normal/my_eye.png"
  ]
}

Keep replace set to false if you only want to add eyes. Setting it to true replaces eyes loaded before this file.

The new eye format

The alpha channel tells MCA what each pixel does:

Alpha	Meaning
0	Transparent
253	Fixed color. MCA keeps the RGB color you painted
254	Tintable eye color mask

Alpha 253 and 254 are markers. They render opaque, so they are not meant to make the eye slightly transparent.

For a new eye texture, use 253 for things that should not change color, such as the sclera, pupil, eyelashes, or other fixed details. Use 254 for the iris pixels that should follow the villager's eye color.

Here is a real marked eye from MCA, enlarged so the pixels are easy to see:

The white, gray, and black parts are fixed pixels. The green pixels are tintable. The original working file is only 64x64 pixels: open or download the template.

Tint mask colors

Pixels with alpha 254 use one RGB channel to choose a tone:

RGB channel	Tone
Red	Shadow
Green	Main eye color
Blue	Highlight

Exactly one RGB channel must be above zero on a tintable pixel. The value of that channel controls the strength of the pixel from 1 to 255.

This example shows all three tint channels in one simple eye shape:

Red becomes the shadow tone, green becomes the main eye color, and blue becomes the highlight. The black and white pixels stay fixed.

Some useful examples:

Pixel	RGBA value
Fixed off-white sclera	254, 251, 249, 253
Full shadow	255, 0, 0, 254
Full main color	0, 255, 0, 254
Full highlight	0, 0, 255, 254
Half-strength main color	0, 128, 0, 254
Transparent	0, 0, 0, 0

The PNG will look red, green, and blue in an image editor. That is normal. Those colors are masks, not the final eye color shown in game.

For example, a basic eye could use fixed off-white pixels for the sclera, green-channel pixels for most of the iris, red-channel pixels around the darker part of the iris, and one or two blue-channel pixels for highlights.

You do not need to make separate textures for blue, green, brown, or custom RGB eyes. MCA applies the selected eye color at runtime.

The same marked texture can therefore appear with completely different eye colors:

How the three tones are colored

For normal eye colors, MCA creates the three tones automatically:

• Primary uses the selected eye color as-is.
• Shadow is roughly half as bright.
• Highlight is halfway between the selected color and white.

This works with arbitrary RGB colors, including colors chosen in the villager editor.

Gender-specific eyes

If an eye should only be available to one gender, use an object instead of a plain texture string:

{
  "replace": false,
  "textures": [
    {
      "id": "example:skins/face/normal/female/my_eye.png",
      "gender": "female"
    },
    {
      "id": "example:skins/face/normal/male/my_eye.png",
      "gender": "male"
    }
  ]
}

Valid values are female, male, and neutral. You can also leave gender out if the eye should be available normally.

Custom tone overrides

Most resource packs do not need this section.

tone_overrides lets one exact selected eye color use custom shadow, primary, and highlight colors instead of the automatic three-tone calculation. MCA uses this for some older eye palettes where the original colors do not follow the normal formula.

Example:

{
  "replace": false,
  "textures": [
    {
      "id": "example:skins/face/normal/special_eye.png",
      "tone_overrides": {
        "#53351d": {
          "shadow": "#53351d",
          "primary": "#7a4d2b",
          "highlight": "#f2dfd1"
        }
      }
    }
  ]
}

The key, in this case #53351d, is the exact eye color selected by the villager. If the selected color does not have an override, MCA uses the normal automatic tones.

All colors must use #RRGGBB format, and each override needs shadow, primary, and highlight.

Old eye textures

If a PNG has no alpha 253 or 254 pixels, MCA treats it as an old-style eye texture.

The old system guesses the material from the painted colors. Bright neutral pixels are treated as sclera, very dark pixels as details, and the remaining colored pixels as the tintable iris. This keeps older resource packs working, but it can be ambiguous when a pale iris pixel looks similar to the sclera.

For new textures, the explicit 253 and 254 format is recommended because you decide exactly which pixels can be tinted.

Alpha 1 is not a special eye marker. Do not rely on it for new textures.

Common mistakes

• Do not use two RGB channels at the same time on an alpha 254 pixel. A tint mask pixel must be red, green, or blue channel based, not a mixture.
• Do not use alpha 255 for a pixel that should change eye color in a marked texture. Use alpha 254 and one mask channel.
• Do not use tone_overrides for every possible color. The normal three-tone system already works with arbitrary RGB colors.
• Use "replace": false unless you intentionally want to replace the existing eye list.
• If an old unmarked eye already works, you can leave it alone. Convert it only if you want explicit control over which pixels are tinted.