skin-spec

A technical specification for Minecraft skins, for developers.

Image Format

Skins are served in a PNG format from Mojang's servers. There is no enforced colour space of images; you should convert explicitly if you need to ensure that a skin is in some standard format. For example:

skinImg, format, err := image.Decode(imageBuffer)

if format != "NRGBA" {
    bounds := skinImg.Bounds()
    skinImg = image.NewNRGBA(bounds)
    draw.Draw(out.(draw.Image), bounds, skinImg, image.Pt(0, 0), draw.Src)
}

Image Dimension

The image dimensions may either be 64 by 32 pixels or 64 by 64 pixels. The former was used by Minecraft versions prior to 1.8, while the latter is accepted by Minecraft versions 1.8 and onwards. Positions of elements remain the same in 1.8, however there have been new "overlays" added to the skins file.

The following image, from the Minecraft Wiki, is a useful reference. Portions included in the pre-1.8 skin version are solid coloured, new elements are checkered.

Transparency

Transparency must be based off of the upper left-hand pixel of the image. Though many skins use standard the standard alpha-channel, others use a solid matte.

Note that mattes should only be removed for components marked "transparent" below, otherwise you may remove actual skin data.

We use the following code in Minotar to "fix" the matte after converting the image to NRGBA, where skin.AlphaSig is simply a four-element slice of the image's first pixel's data:

// Removes the skin's alpha matte from the given image.
func (skin *mcSkin) removeAlpha(img *image.NRGBA) {
    // If it's already a transparent image, do nothing
    if skin.AlphaSig[3] == 0 {
        return
    }

    // Otherwise loop through all the pixels and fix em
    for i := 0; i < len(img.Pix); i += 4 {
        if img.Pix[i+0] == skin.AlphaSig[0] &&
            img.Pix[i+1] == skin.AlphaSig[1] &&
            img.Pix[i+2] == skin.AlphaSig[2] &&
            img.Pix[i+3] == skin.AlphaSig[3] {
            img.Pix[i+3] = 0
        }
    }
}

Skin Serving

Prior to 1.8 Release

Originally Mojang used Amazon S3 to host all their skins: http://s3.amazonaws.com/MinecraftSkins/%Username%.png

Valid users (case sensitve) will still respond with an archived skin PNG which has Content-Type: application/octet-stream and are sent with accurate Last-Modified timestamps that can assist with caching.

Invalid users will result in a 403 Forbidden and a Content-Type: application/xml error code of AccessDenied. This will likely also happen for users which were created after the switch away from S3 and therfore don't have a skin hosted there (untested).

Since 1.8 Release

Along with the switch to UUID, Mojang has made efforts to reduce the cost and strain on their infrastructure by making the multiplayer Minecraft server deliver the skin/textures to the client (after being verified by Mojang). CloudFront is more heavily used as well as EC2 app servers for returning JSON data. S3 is (likely) still used for backend storage of textures.

Initial Client side lookups are made to EC2 app servers behind a CloudFront endpoint (not caching, but reducing the impact of malicoius traffic) https://sessionserver.mojang.com/session/minecraft/profile/%UUID% with the response Content-Type: application/json:

{  
    "id":"d9135e082f2244c89cb0bee234155292",
    "name":"clone1018",
    "properties":[  
        {  
            "name":"textures",
            "value":"eyJ0aW1lc3RhbXAiOjE0MjAzMDE3MzYwMjIsInByb2ZpbGVJZCI6ImQ5MTM1ZTA4MmYyMjQ0Yzg5Y2IwYmVlMjM0MTU1MjkyIiwicHJvZmlsZU5hbWUiOiJjbG9uZTEwMTgiLCJ0ZXh0dXJlcyI6eyJTS0lOIjp7InVybCI6Imh0dHA6Ly90ZXh0dXJlcy5taW5lY3JhZnQubmV0L3RleHR1cmUvY2Q5Y2E1NWU5ODYyZjAwM2ViZmExODcyYTkyNDRhZDVmNzIxZDZiOWU2ODgzZGQxZDQyZjg3ZGFlMTI3NjQ5In19fQ=="
        }
    ]
}

The sessionserver.mojang.com domain uses very aggressive rate-limiting and will return a 429 429 [sic] if the same UUID is requested from the same source IP within 30 seconds.

The textures property is Base64 encoded string which decodes into JSON (%TimeStamp% is milliseconds since epoch):

{  
    "timestamp":%TimeStamp%,
    "profileId":"d9135e082f2244c89cb0bee234155292",
    "profileName":"clone1018",
    "textures":{  
        "SKIN":{  
            "url":"http://textures.minecraft.net/texture/cd9ca55e9862f003ebfa1872a9244ad5f721d6b9e6883dd1d42f87dae127649"
        }
    }
}

The textures object can have a SKIN and/or CAPE object, each with a url inside.

Mojang have also implemented a similar style lookup address as they had with S3 which allows usernames lookups to be made to: http://skins.minecraft.net/MinecraftSkins/%Username%.png

The response for a valid user (case insensitive) is a 301 Moved Permanently redirect to http://textures.minecraft.net/texture/%TextureHash% which then serves the skin as Content-Type: image/png.

The response for invalid users is a 404 Not Found and all requests (valid or not) are cached by CloudFront.

The %TextureHash% appears to be a hash of the skin which is then linked to the account.

It is worth noting that there appears to be no optimization of the skins being served from the textures.minecraft.net address. In some instances where someone has used certain programs which add large amounts of meta data to the PNGs, you can easily end up with skins 10x the size. This is worth considering if you plan to cache them.

Components

The following is a list of components of the Minecraft skin.

• Version number indicates the version the component is present in. "0" indicates all versions.
• Coordinates is in the format (x1, y1, x2, y1) indicating the coordinate bounds the component can be found in the skin.
• Transparent indicates

Version	Part	Side	Coordinates	Transparent
0	Head	Top	(8, 0, 16, 8)	✗
0	Head	Bottom	(16, 0, 24, 8)	✗
0	Head	Right	(0, 8, 8, 16)	✗
0	Head	Front	(8, 8, 16, 16)	✗
0	Head	Left	(16, 8, 24, 16)	✗
0	Head	Back	(24, 8, 32, 16)	✗
0	Helm	Top	(40, 0, 48, 8)	✓
0	Helm	Bottom	(48, 0, 56, 8)	✓
0	Helm	Right	(32, 8, 40, 16)	✓
0	Helm	Front	(40, 8, 48, 16)	✓
0	Helm	Left	(48, 8, 56, 16)	✓
0	Helm	Back	(56, 8, 64, 16)	✓
0	Right Leg	Top	(4, 16, 8, 20)	✗
0	Right Leg	Bottom	(8, 16, 12, 20)	✗
0	Right Leg	Right	(0, 20, 4, 32)	✗
0	Right Leg	Front	(4, 20, 8, 32)	✗
0	Right Leg	Left	(8, 20, 12, 32)	✗
0	Right Leg	Back	(12, 20, 16, 32)	✗
0	Torso	Top	(20, 16, 28, 20)	✗
0	Torso	Bottom	(28, 16, 36, 20)	✗
0	Torso	Right	(16, 20, 20, 32)	✗
0	Torso	Front	(20, 20, 28, 32)	✗
0	Torso	Left	(28, 20, 32, 32)	✗
0	Torso	Back	(32, 20, 40, 32)	✗
0	Right Arm	Top	(44, 16, 48, 20)	✗
0	Right Arm	Bottom	(48, 16, 52, 20)	✗
0	Right Arm	Right	(40, 20, 44, 32)	✗
0	Right Arm	Front	(44, 20, 48, 32)	✗
0	Right Arm	Left	(48, 20, 52, 32)	✗
0	Right Arm	Back	(52, 20, 56, 32)	✗
1.8	Left Leg	Top	(20, 48, 24, 52)	✗
1.8	Left Leg	Bottom	(24, 48, 28, 52)	✗
1.8	Left Leg	Right	(16, 52, 20, 64)	✗
1.8	Left Leg	Front	(20, 52, 24, 64)	✗
1.8	Left Leg	Left	(24, 52, 28, 64)	✗
1.8	Left Leg	Back	(28, 52, 32, 64)	✗
1.8	Left Arm	Top	(36, 48, 40, 52)	✗
1.8	Left Arm	Bottom	(40, 48, 44, 52)	✗
1.8	Left Arm	Right	(32, 52, 36, 64)	✗
1.8	Left Arm	Front	(36, 52, 40, 64)	✗
1.8	Left Arm	Left	(40, 52, 44, 64)	✗
1.8	Left Arm	Back	(44, 52, 48, 64)	✗
1.8	Right Leg Layer 2	Top	(4, 48, 8, 36)	✓
1.8	Right Leg Layer 2	Bottom	(8, 48, 12, 36)	✓
1.8	Right Leg Layer 2	Right	(0, 36, 4, 48)	✓
1.8	Right Leg Layer 2	Front	(4, 36, 8, 48)	✓
1.8	Right Leg Layer 2	Left	(8, 36, 12, 48)	✓
1.8	Right Leg Layer 2	Back	(12, 36, 16, 48)	✓
1.8	Torso Layer 2	Top	(20, 48, 28, 36)	✓
1.8	Torso Layer 2	Bottom	(28, 48, 36, 36)	✓
1.8	Torso Layer 2	Right	(16, 36, 20, 48)	✓
1.8	Torso Layer 2	Front	(20, 36, 28, 48)	✓
1.8	Torso Layer 2	Left	(28, 36, 32, 48)	✓
1.8	Torso Layer 2	Back	(32, 36, 40, 48)	✓
1.8	Right Arm Layer 2	Top	(44, 48, 48, 36)	✓
1.8	Right Arm Layer 2	Bottom	(48, 48, 52, 36)	✓
1.8	Right Arm Layer 2	Right	(40, 36, 44, 48)	✓
1.8	Right Arm Layer 2	Front	(44, 36, 48, 48)	✓
1.8	Right Arm Layer 2	Left	(48, 36, 52, 48)	✓
1.8	Right Arm Layer 2	Back	(52, 36, 64, 48)	✓
1.8	Left Leg Layer 2	Top	(4, 48, 8, 52)	✓
1.8	Left Leg Layer 2	Bottom	(8, 48, 12, 52)	✓
1.8	Left Leg Layer 2	Right	(0, 52, 4, 64)	✓
1.8	Left Leg Layer 2	Front	(4, 52, 8, 64)	✓
1.8	Left Leg Layer 2	Left	(8, 52, 12, 64)	✓
1.8	Left Leg Layer 2	Back	(12, 52, 16, 64)	✓
1.8	Left Arm Layer 2	Top	(52, 48, 56, 52)	✓
1.8	Left Arm Layer 2	Bottom	(56, 48, 60, 52)	✓
1.8	Left Arm Layer 2	Right	(48, 52, 52, 64)	✓
1.8	Left Arm Layer 2	Front	(52, 52, 56, 64)	✓
1.8	Left Arm Layer 2	Left	(56, 52, 60, 64)	✓
1.8	Left Arm Layer 2	Back	(60, 52, 64, 64)	✓