Faces overview

Punchy! Moves draws a living face on every player’s head: lids that blink, pupils that follow where the head points, brows that move, and looks that change with what the player does. You do not need a pack or any setup to see it. This page is for players who want to tune their own face, skin makers who want the eyes found correctly, and pack makers who want to add looks, eye shapes and face animation.

Before you start

• Install Punchy! Moves (Getting started) and look at your character in third person. First person draws no face.
• The face settings and the face editor live in the Face tab of Punchy’s new menu, in its Punchy Moves group. Punchy!‘s menu key, F8 by default, opens the menu. Without that menu the face still works with its defaults, and the settings file config/punchy_moves/face.json holds the same options.
• Everything on this page happens on your own screen. Nothing is sent to a server and your skin file is never changed, so faces work on any server and on any player whose skin has eyes it can find.

Video coming soon

How the face is drawn

The face is a render layer on the player’s head. The first time Moves draws a skin it reads its pixels once and finds the eyes on them (see the next section). Then each frame it paints lids, whites, pupils, brows and marks over the face texels.

A face is made of these parts:

• Lids: blinks on each player’s own rhythm (one blink in eight is doubled), half-closed lids, winks, lids that slant for a cross or a sad look, lower lids that rise, and cheeks that push them up in a smile.
• Pupils: they follow the head up, down and to the sides, glance aside, sway, tremble, and turn toward a watcher or the nearest monster.
• Brows: up, down, one at a time, tilted for a worried or an angry look, bobbing to music.
• Marks: blush, tears, a drop of sweat, dark rings under the eyes, the anger vein and a glint in the pupils.
• Drawn eye shapes: an eye can turn into pixel art for a moment, sized to the eye (see Eye shapes).

Three things decide what the parts do at any moment:

1. Gaze is on by default: the eyes and brows follow the head, emotes included, until you switch off Gaze in the Always group of the Face tab.
2. Reactions pick a look, a ready-made set of all these parts. There are 119 reactions, such as squinting in the rain, winking while throwing a snowball, looking scared near a warden or falling asleep in a bed. The strongest reaction that applies sets the whole look, and the strongest one that sets a blink pace sets the pace. Face reactions lists them all.
3. Clips can take over the face for a while: a clip can hold a look or key single parts (see Channels in a clip).

Looks ease into each other over three ticks, and a change of eye shape passes through a quick blink. A stronger look also stays up to four ticks after its reaction stops, so two reactions never swap tick by tick.

Standing still

While you stand still the face comes to life by itself. After two seconds of standing still, the pupils glance aside now and then and the brows drift. After the daydream time (30 seconds by default) the lids droop and the blinks slow down. Glances and the brow drift also need the Glances setting on, and they pause for a moment while the head turns fast or while a stronger reaction (priority above 300) is playing.

While you stand still, the face also has idle moments. About every 20 to 45 seconds, for three seconds, it takes one of the idle looks Sly, Curious, Bored, Wink, Smug or Happy. The Idle moments switch in the Face tab turns them off, and a pack sets the wait with idle_events (see Camera and features).

Where the face is not drawn

• No face is drawn for a spectator or for an invisible player you cannot see.
• An invisible player you can see gets a see-through face, like the body. Your own player gets the camera’s fade while the camera fades it.
• Some reactions only work on your own player, because the game never tells your client other players’ food or level, and Moves notices block use, a thrown snowball, egg, wind charge, ender pearl, potion or bottle o’ enchanting, lit fires, shears and bow or crossbow shots only when you do them yourself. A trident throw is worked out from how the trident is used, so it plays on other players too. Other players’ effects show as of when they came into view.

How the face finds the eyes

The first time Moves draws a skin it looks for the eyes on it. It reads these layouts:

• two eyes as usual, with their whites, pupils and the brows over them, also brows painted under bangs
• one eye in the middle of the face (a cyclops)
• two eyes that touch in the middle
• eyes of two colors, two sizes or at two heights
• one eye with the other hidden under hair
• dark eyes without a white, which glide as a whole when they look aside

A texel counts as part of an eye when its color is clearly different from the skin tone, and the finder reads what you see: a hat-layer texel that is at least half opaque counts in place of the face texel under it. When it finds nothing, that skin has no face, and the finder can still misread an eye. For both cases you can mark the eyes yourself.

A skin gets its eyes from the first of these that exists:

1. Your hand marks, made in the face editor’s Marks tab. They stay on your computer.
2. The skin’s face marker, a small block of pixels that a skin carries, for skin makers: The face marker.
3. The finder, which reads the skin by itself.

An eye in the middle

An eye in the middle is the only eye, so it does what either eye does:

• It closes as far as the larger of the two lids, so a wink closes it.
• It takes the shape both eyes share. When one eye is open it takes the other eye’s shape, except a plain shut line, which leaves it open. When the two shapes differ and neither is open, it takes the right eye’s.
• It squeezes shut from both sides, and it cries one tear from its middle.
• Each half of its brow follows its own side.

Glints painted on the skin

A skin can paint a glint over an eye on its hat layer. The face draws that glint on the eye itself, under the lids, so a closing lid hides it. With the eye sparkle set to Skin’s own it also moves with the pupil. A drawn shape or a blank eye draws no glint.

Set up your own face

These settings are yours alone and save as soon as you change them.

Video coming soon

The settings

Eye sparkle gives each pupil a glint that moves with it. Line is a line along the pupil’s side toward the nose and Dot a small dot near its top. Looks that sparkle, such as Excited and Sparkly, add a second line or dot. Skin’s own is the glint a skin paints on its eye, which then moves with the pupil (a skin without one shows none). Off means no glints but those the skin paints.

The Sparkle color presets are white FFFFFF, cream FFF1CC, gold FFD447, sky 9EDCFF, aqua 5FF2E0, mint A6F2B8, pink FFA8D2, lilac CFB2FF and red FF5C5C. The Line color of closed eyes picker offers 161616, 3B2A20, 26285A, 4A2463, 6B1F2A, 1F4D3A, 6E7380, FFFFFF and FF4F7E, plus Each eye’s own color to go back to auto.

The reaction switches sit in these groups: Always, Standing about, Running and crouching, Jumps and falls, Flying, Climbing, Water and weather, Riding, Combat, Items and tools, Fishing, Body and effects, Places and music, Creatures and people and Emotes.

Edit face.json by hand

Close the game first: the file is read once, when the settings are first used. This file is valid as it stands, and any key you leave out keeps its default:

{
  "over_hat": true,
  "blinking": true,
  "glances": true,
  "blink_seconds": 2.5,
  "daydream_seconds": 45,
  "sparkle": "dot",
  "sparkle_color": "#FFD447",
  "line_color": "auto",
  "reactions": {
    "daydream": false
  },
  "trigger_looks": {}
}

The file is read as one piece. A value that cannot be read, such as a color that is not hex, stops the read at that key. The game reads the keys in the order of the example above: the keys before it in that order are used and the keys after it keep their defaults. A file that does not parse at all keeps every default.

The face editor

In the Face tab, Face editor has an Open button. The editor shows your own player, live, beside the grid of your skin’s face with what was found on it. Drag the player to turn it. Face and Body switch the preview between the head and the whole player. It has three tabs:

• Marks: mark eyes, pupils and brows by hand with the Eye, Pupil, Brow and Erase tools, go back with Reset to found, or press Export skin to write a copy of your skin with the marks inside it.
• Test: Blink, Look left, Look right and Raise brows, play any reaction through its trigger, show any look as it is, and give a reaction another look.
• Style: Over the hat layer, Eye sparkle with Sparkle color, and Line color of closed eyes, the same options as the Face tab.

Each group of touching marks is one eye (touching side by side or one above the other, not corner to corner), so any layout can be marked, even three eyes. Hand marks are kept in config/punchy_moves/faces as one small text file per skin. Export skin writes config/punchy_moves/faces/<skin>_with_face.png. Use that copy as your skin. Punchy! Moves reads the marks from the skin file it downloads. Export skin works only on a 64 by 64 skin that has a face: other skins are refused. How the marks are stored in the skin is on The face marker.

Video coming soon

Make a look of your own

A look is one small JSON file. You can put it in your own config folder with no pack, and a pack can ship the same file. This walks you from nothing to a look that plays when you start running.

The eye shape, faces/shapes/gem.json:

{
  "closed": false,
  "color": "#4FC3F7",
  "colors": { "2": "#0B3C5D" },
  "on_white": false,
  "mirror": true,
  "grids": {
    "4x2": [".##.", "#22#"],
    "4x4": [".##.", "####", "#22#", ".##."]
  }
}

The look, faces/looks/cheeky.json:

{
  "extends": "happy",
  "lid_left": 1,
  "cheeks": 1,
  "blush": 1,
  "brows": 0.6,
  "tilt": -0.5,
  "eyes": ["gem", "open"]
}

"extends": "happy" starts from the built-in Happy look, so every part you do not set comes from it. eyes is the right eye first, then the left: the right eye is drawn as gem, the left stays the painted eye (open) and is shut by lid_left. Step 7 stored your pick in trigger_looks in face.json as "kickoff": "cheeky".

The parts of a look

A look file may set any of these. Values are clamped when the face is drawn, so a value outside its range acts as the nearest end, except swing, tremble and bob, which are not clamped.

The 40 looks that come with Moves

These are in the editor’s order: neutral, happy, joyful, excited, sparkly, love, proud, smug, relaxed, zen, wink, sly, sneaky, curious, focused, squint, determined, furious, menacing, strain, surprised, shocked, scared, nervous, worried, sad, crying, pain, wince, dizzy, knocked, sick, tired, sleepy, bored, cold, hot, blinded, wary and shut.

Emotes and clips can also use these short names: cross, calm, flutter, narrow, wink_left, wink_right, startled, glum, uneasy, cheery, intent, aghast, hurting, drowsy, laugh, angry, glance_left and glance_right. They are not in the editor’s list.

Eye shapes

An eye shape is what an eye looks like while it is drawn instead of painted. Moves has nine:

line, arc, cup, press and cross are closed shapes: a blink draws no lid over them, and a change between two closed shapes skips the quick blink. spiral, heart and blank take the blink.

A pack or a player can redraw any of them but open and blank, and can add shapes of their own with a file in faces/shapes.

In a grid row, . is empty, # paints the shape’s own color and 2 to 9 paint the other colors. (The letters X, x, o, O, 1 and * also paint the own color.)

Where faces come from

A later layer wins by name: your own folder over the packs, a higher pack over a lower one, and all of them over the built-in ones. Files must sit directly in looks or shapes: a file in a subfolder is not read. A name is the file name without .json, lower-cased with spaces turned into underscores. Moves reads the files when the game starts and again on every resource reload.

Faces in packs and clips goes through all of this file by file. The short version of each follows.

Reaction changes in a pack

A pack can change which look a reaction plays, and how strong the reaction is, with faces/triggers.json. Save it as assets/punchy_moves/faces/triggers.json in a resource pack. Each key is a reaction’s id. A name gives that look. An object takes look and priority. This file is valid as it stands:

{
  "kickoff": "excited",
  "shear": { "look": "smug" },
  "stride": { "priority": 450 }
}

Every pack’s copy is read and the higher pack wins, but its entry replaces the lower pack’s entry whole, priority included. Your own pick in the editor’s Test tab is stored in face.json, wins over a pack’s change, and your reaction switches still apply. A triggers.json that does not parse is skipped whole. You can see every reaction’s id and priority on Face reactions.

A look for a whole clip

Any clip can hold one look for its whole length with face, a look’s name or an object with look and mix (how much of the face the clip takes over, 1 by default). The two clips below are valid as they stand. Save them as assets/punchy_moves/animations/face_clips.json in a resource pack (a pack also needs a pack.mcmeta: Faces in packs and clips shows a whole pack as files):

{
  "format_version": "1.8.0",
  "animations": {
    "wake_up": {
      "animation_length": 2.5,
      "face": "sleepy",
      "bones": {
        "head": { "rotation": { "0.0": [12, 0, 0], "2.5": [0, 0, 0] } }
      }
    },
    "proud_pose": {
      "animation_length": 2.0,
      "face": { "look": "proud", "mix": 0.8 },
      "bones": {
        "head": { "rotation": { "0.0": [0, 0, 0], "1.0": [-6, 0, 0], "2.0": [0, 0, 0] } }
      }
    }
  }
}

The look is trimmed, lower-cased, and spaces become underscores. A face object whose look is an object, or a list that does not hold exactly one name, ends that clip and the rest of its file: the clips above it stay loaded.

Faces in clips come from a pack’s clips. The player’s own config folder holds looks, shapes and settings, and no animations.

A look for an emote

An emote in a pack’s compat file can name the look that plays with it, even when its clip has no face of its own. Save this one as assets/punchy_moves/compat/emotes.json:

{
  "format_version": 2,
  "emotes": {
    "entries": [
      { "id": "wave", "display_name": "Wave", "animation": "wave", "face": "cheery" },
      { "id": "wink", "display_name": "Wink", "animation": "wink_wave", "face": "wink_left" }
    ]
  }
}

This file assumes your pack has clips called wave and wink_wave: make them as in Create an animation, or put the names of clips you already have in animation. The face is found by the clip, so two emotes that share a clip share the first face given.

face (or expression) is matched exactly as typed against the built-in look names and the short names, in lower case. An emote with no face, a capital letter, a space or a look that only a pack defines plays Happy. Only your own emotes carry a face. See Compat files and Keys and emotes.

Channels in a clip

A clip can key the face itself. The face is a set of bones named face_... in the same clip, keyed like any other bone. Moves reads each bone’s position y (the pupils read x as well), blends it with the clip’s layer and eases it in and out with it. No cubes are needed, so any tool that writes the animation format can do it. A face key takes lerp_mode and easing like any other key, and a bone you do not key stays at 0 and leaves the face alone.

Units are the face’s own, shares of an eye and texels on the skin, not model pixels, so the same keys work on every skin.

Each frame, every part is the reactions’ look less the share face_mix takes over, plus each keyed look by its weight, plus the keyed parts. With no face_mix, keyed parts simply add to whatever the reactions show, such as an extra blink or a raised brow. An eye shows its strongest keyed shape past 0.5. A bone with any other face_ name is kept but changes nothing on the face.

A clip’s face shows over every reaction up to a long fall and a hard landing. Only lava, a hit from behind, a swelling creeper, a warden, the hurt startle, sleeping and dying show over it.

Here is a clip that holds a look for a moment, winks, then looks cross. It is valid as it stands. Save it as assets/punchy_moves/animations/cheer.json in a resource pack:

{
  "format_version": "1.8.0",
  "animations": {
    "cheer": {
      "animation_length": 3.0,
      "bones": {
        "face_mix": { "position": { "0.0": [0, 0, 0], "0.2": [0, 1, 0], "2.7": [0, 1, 0], "3.0": [0, 0, 0] } },
        "face_look_happy": { "position": { "0.0": [0, 1, 0], "1.0": [0, 1, 0], "1.2": [0, 0, 0] } },
        "face_shape_arc_left": { "position": { "1.2": [0, 0, 0], "1.25": [0, 1, 0], "1.8": [0, 1, 0], "1.85": [0, 0, 0] } },
        "face_cheeks": { "position": { "1.2": [0, 0, 0], "1.3": [0, 1, 0], "1.8": [0, 1, 0], "1.9": [0, 0, 0] } },
        "face_brows": { "position": { "1.9": [0, 0, 0], "2.2": [0, -0.75, 0], "2.7": [0, 0, 0] } },
        "face_tilt": { "position": { "1.9": [0, 0, 0], "2.2": [0, -1, 0], "2.7": [0, 0, 0] } },
        "face_anger": { "position": { "2.0": [0, 0, 0], "2.1": [0, 1, 0], "2.5": [0, 1, 0], "2.6": [0, 0, 0] } }
      }
    }
  }
}

A channel holds its first key’s value before that key. A lid key at 1.0 with nothing before it would stay shut from the start of the clip, so key it at 0 first, as face_cheeks is keyed at 1.2 above. Moves mirrors a pose only for the music listening and map view poses, when the hand that holds them is the left one. There the _right and _left face bones swap and the pupils’ x flips. Every other clip is found by its _left or _right name and is not mirrored.

The tools that make faces

Faces are made in Punchy! Studio, which draws them on your own skin as Punchy! Moves does:

• Studio’s Face workspace has the Faces list (Looks, Eye shapes, Reactions), New Look and New Eye Shape, every part of a look as a number field you can drag or type into, per-size grids with colors, and Key in Clip. Studio’s Game view, in the Animation tab, plays the open clip on your own player and shows the pack’s looks and eye shapes live, but not reaction picks: test a reaction pick in the game after the pack loads. See Punchy! Studio and Game view. The in-game editor is on Face editor.
• The Blockbench plugin keys looks, eye shapes and the channels above from its Moves Face panel and draws the face on the rig’s head as you scrub. See The Blockbench rig.
• Any other tool that keys bones in the Bedrock animation format can key the face with the bone names in the table.

Things that go wrong

• No face at all. The finder found no eyes on that skin. Open the face editor, use Marks to paint the eyes, and press Export skin to get a copy of your skin that carries the marks.
• The eyes are in the wrong place. The finder can misread an eye. Mark it by hand: your marks come first.
• Hair or glasses hide the face. Turn on Over the hat layer.
• A look does nothing. The file is in a subfolder, is not valid JSON, or has not been loaded yet. A file name is lower-cased, so Cheeky.json is the look cheeky. Restart the game and read the log: unreadable face files in your config folder are named in warnings whose message starts with Face: when the game starts. F3+T reloads your files but does not log their problems (problems in resource pack face files are logged on every reload).
• A look is missing from the list. A look is left out when extends names an unknown look, eyes names an unknown shape, or pupils or brows has too few numbers. The other files still load.
• An eye shape is missing. It has no usable grids, a grid whose rows do not match its key, or a color that is not line or hex.
• An emote shows Happy. Its face is not a built-in look or short name written exactly in lower case.
• The sparkle color or the settings after it do not load. A bad value in face.json stops the read at that key.
• A reaction never shows. Its switch in the Face tab is off, or a stronger reaction is playing. The strongest reaction that applies sets the look.
• First person shows no face. Moves draws none there.

Related pages

• Faces in packs and clips: every file, folder and key of a face pack.
• Face reactions: all 119 reactions with their priorities and what turns each on.
• The face marker: for skin makers, the block of pixels that carries your marks.
• Face editor: the Face tab and the face editor in the game.
• Punchy! Studio: making faces in Studio’s Face workspace.
• Compat files and Keys and emotes: putting a clip and its look on the emote wheel.
• Troubleshooting and the FAQ.