The face marker

Punchy! Moves finds the eyes on a skin by itself, and many skins get a face with no work. When it reads yours wrong, or finds nothing, you can mark the eyes, pupils and brows by hand in the game, then export a copy of your skin that carries those marks. Punchy! Moves reads the marks from the skin file it loads, so a player with Punchy! Moves whose game loads that file as your skin sees the face you marked. This page is for skin makers and for players who want their own face right.

Before you start

• Install Punchy! Moves, from Modrinth or CurseForge (Getting started has the steps). The face editor works on your own player, so join a world or a server first.
• The face editor is in the Face tab of Punchy’s new menu, in its Punchy Moves group. Without that menu there is no Face tab, so install Punchy! with its new menu, from Modrinth or CurseForge.
• Your skin must be 64 by 64 pixels. The marker cannot be written to other sizes.
• The marks say where the eyes are. The colors still come from your skin, so paint the eyes on the skin first.
• Outside the game you need a way to upload a skin and, for the optional check of the PNG at the end of “Check what other players will see”, Blockbench (Punchy! Studio does the same check in a world). The script in “A complete example” needs Python 3 with the Pillow library.

Where marks live

A skin’s eyes come from the first of these that exists:

You make hand marks in the game. Export skin then copies them into the marker of a new PNG. Players without Punchy! Moves see that PNG as your normal skin, because no part of the player model draws the marker’s pixels.

A skin with no eyes found shows no face to other players with Punchy! Moves until its file carries a marker. Mark the eyes, export the skin and set the exported PNG as your skin; the check in “Check what other players will see” shows whether the marker came through.

Mark the eyes and export the skin

Video coming soon

Reset to found removes all your marks for this skin and the face goes back to the skin’s marker, or to what the finder finds. The line under the buttons says Marks removed: the face uses what was found on the skin. Erasing every mark one by one does the same.

If Export skin says Only a 64 by 64 skin with a face can be exported., the skin is another size or has no marks and no found eyes. Mark at least one eye first.

If you press Export skin with no hand marks, the marker holds the eyes in use: the ones the skin’s marker holds, or else the ones the finder found. That locks in a reading you are happy with.

Check what other players will see

Your own hand marks win on your own screen, so the editor shows your marks even when the skin has no marker yet. To see what everyone else gets, check the skin file itself:

You can also check the PNG before you ever join a game, in Blockbench: press Use a skin in the Moves Face panel on the Punchy! Moves rig, and the panel says how many eyes and brows Moves finds on that skin. Once you are in a world with the PNG set as your skin, Punchy! Studio’s Face workspace shows the same reading for your player (Punchy! Studio), as long as you have no hand marks for the skin: Studio uses them first, as the game does on your screen.

A complete example

The marks file

Your hand marks are one small text file. This one marks two eyes in the fifth row of the face, a pupil in each, and a brow over each eye. It is also a face you can type by hand:

........
........
........
.bb..bb.
.ep..pe.
........
........
........

Eight lines of eight characters, one character per pixel of the face, from the top left:

Where the file is and what it is called:

• The folder is config/punchy_moves/faces. The file is named after your skin and ends in .txt.
• A skin you downloaded from the skin servers is named by its hash, a long string of letters and digits. A skin from the game or a resource pack is named from its namespace and its path, joined by an underscore, in lower case, with every character other than letters, digits, _, . and - turned into _.
• The easiest way to find your file is to click one mark in the editor and look in the folder for the new .txt. The exported <same name>_with_face.png sits beside it.
• The file is saved at every click. When the last mark is cleared, the file is deleted.
• To edit it by hand, close the game first. The game reads each file once, the first time it needs that skin’s marks. Any character other than e, p or b counts as nothing, and so does a missing character or line. Extra characters are ignored.

The marker, written with a script

Export skin is the way most people should write the marker. If you build skins with a script, this does the same job. It writes the marks above into the block at x 56 to 63, y 16 to 31 of a 64 by 64 PNG.

# add_marker.py: writes the Punchy Moves face marker into a 64 by 64 skin.
# Usage: python add_marker.py skin.png skin_with_face.png
import sys
from PIL import Image

# The face's 64 pixels (the head's front, 8 by 8), row by row:
# . nothing, e eye, p pupil, b brow
FACE = [
    "........",
    "........",
    "........",
    ".bb..bb.",
    ".ep..pe.",
    "........",
    "........",
    "........",
]

COLORS = {".": (0x00, 0x00, 0x00), "e": (0xFF, 0xFF, 0xFF),
          "p": (0x20, 0x40, 0xC0), "b": (0x80, 0x40, 0x20)}
KINDS = ".epb"
SIGNATURE = b"punchy moves face rig v1"  # 24 bytes, 3 per pixel, 8 pixels
X, Y = 56, 16

marks = [KINDS.index(ch) for row in FACE for ch in row]

h = 0x2F1D3B
for k in marks:
    h = (h * 31 + k + 7) & 0xFFFFFF

skin = Image.open(sys.argv[1]).convert("RGBA")
if skin.size != (64, 64):
    sys.exit("The marker needs a 64 by 64 skin.")
px = skin.load()

for y in range(Y, Y + 16):                      # clear the block to opaque black
    for x in range(X, X + 8):
        px[x, y] = (0, 0, 0, 255)
for i in range(8):                              # row 0: the signature
    px[X + i, Y] = (*SIGNATURE[i * 3:i * 3 + 3], 255)
for r in range(8):                              # rows 1 to 8: the marks
    for c in range(8):
        px[X + c, Y + 1 + r] = (*COLORS[FACE[r][c]], 255)
px[X, Y + 9] = (h >> 16, (h >> 8) & 0xFF, h & 0xFF, 255)   # row 9: the checksum

skin.save(sys.argv[2])

For this face the checksum pixel is #253C9B. If your own copy of the script writes another value for the same FACE, the marker will not be read.

How the marks become eyes

Marks only say where. Punchy! Moves builds the rig from them over your skin’s own pixels, so the lids, whites and pupils keep your skin’s colors. These are the rules, so you know what to mark.

• One group, one eye. Eye and pupil marks that touch side by side or one above the other (not corner to corner) form one eye. There can be any number of them, so three eyes work. The eye’s box is the box around the group.
• The pupil is the run of columns that hold pupil marks, starting at the first such column. An eye with no pupil mark does not glide its pupil when it looks aside.
• The white is the lightest pixel of the skin among the eye’s own e marks. It is used only when the eye also has a pupil mark, so an eye with pupil marks and no e mark has no white.
• The lid takes its color from the nearest skin-toned pixel above the eye, in the eye’s columns. If there is none, it takes the nearest skin-toned pixel anywhere on the face. Only if the face has none does it take the pixel above the eye’s left column.
• The hat layer. An eye whose box is more than half covered by solid hat pixels is drawn on the hat layer.
• One group of brow marks is one brow. Its bar is the marked row of the group with the most marks, from its first to its last marked column. A brow takes its skin color from the lid of the eye under it, or from the nearest skin-toned pixel above the brow when no eye is under it. If no skin-toned pixel is found, it takes the pixel above the brow’s first column.
• Order. Eyes are taken from left to right by their left column, and so are brows.
• Eyes that touch in the middle. A group that crosses the middle of the face is split down the middle into two eyes when it has pupil marks on both sides and no pupil across the two middle columns. A pupil across the middle columns makes one eye in the middle, a cyclops. See Faces for how an eye in the middle behaves.

How the marker is stored

The marker is a block of 8 by 16 pixels at x 56 to 63, y 16 to 31 of the skin file, to the right of the right arm’s base. The right arm’s pixels end at x 55 on a classic skin and at x 53 on a slim skin, and no overlay layer or other part uses that corner, so the skin looks the same with or without it.

The signature, pixel by pixel from x 56 to x 63:

Each mark pixel has the color of its kind:

The checksum is worked out like this. Start with the number 0x2F1D3B. Go through the 64 marks in order, row by row from the top left, with nothing as 0, eye as 1, pupil as 2 and brow as 3. For each mark, multiply the number by 31, add the mark and 7, and keep only the lowest 24 bits. The final number is the pixel’s color, with the top byte as red.

The game reads only the colors of the marker pixels, never their alpha. Each of the 64 mark pixels may be off by up to 24 in any channel from its kind’s color. The signature and the checksum pixel must match the table and the checksum exactly. Export skin and the script above write every pixel of the block fully opaque.

The marker is read when the game first draws that skin, for skins downloaded from the skin servers and for skins that come from a resource pack. Punchy! Moves sends nothing to a server; the marker travels only inside the skin file.

Things that make the game ignore the marker

A marker is all or nothing. When any of these is wrong, the game skips the whole marker and uses the finder, with no message on screen.

• The skin is not 64 pixels wide. A 128 by 128 skin cannot carry a marker, and Export skin refuses it.
• One of the eight signature pixels is not the exact color from the table.
• A mark pixel is not close to any mark color: for each of the four colors, at least one channel is more than 24 away.
• The checksum pixel does not match the 64 marks. This happens when you change a mark pixel by hand and do not recompute the checksum.
• An image editor, a lossy format or a conversion changed the colors in the block. Keep the skin a lossless PNG, and keep the marker pixels fully opaque, since some editors throw away the colors of transparent pixels.

Why my marks do not show

• The editor does nothing when I click. The editor works on your own player, so you must be in a world or on a server. Click inside the 8 by 8 grid. The tool highlighted when the editor opens is Eye, and a click paints it. The other tools are Pupil, Brow and Erase.
• Other players do not see my marks. Hand marks stay on your computer. Press Export skin and upload the new PNG as your skin, then run the check in “Check what other players will see” to confirm the marker is still in the skin you get back. Players without Punchy! Moves see no face either way.
• I redrew my skin and the eyes moved. The marker holds positions in the 8 by 8 grid, not colors. When you move or resize the eyes in the skin, mark them again and export again.
• My own screen and the log disagree. Your hand marks come first, then the marker, then the finder. Press Reset to found to see the marker’s face on your own screen.
• The face has no pupil movement. The pupil moves only on an eye that has both a pupil mark and at least one eye mark, because the white comes from the eye marks. An eye missing either has no white and does not move its pupil: it shifts as a whole by up to half a texel when the face looks aside. Mark the pupil pixels with Pupil and the pixels around them with Eye for a moving pupil.
• A cyclops split into two eyes. The group crossed the middle with pupil marks on both sides. Put pupil marks across the two middle columns of the grid, side by side, in one row.

Related pages

• Faces: how the face is drawn, how the finder reads a skin, and the face settings.
• Face editor: the Face tab and the in-game face editor, with every face setting and reaction switch.
• Faces in packs and clips: looks, eye shapes and face keys in a pack.
• Face reactions: all 119 reactions and what they play.
• Punchy! Studio: the Face workspace, which shows the face on your own skin in a world.
• Blockbench rig: the rig with the Moves Face panel and its Use a skin button.
• Troubleshooting: when something does not load.