Skin spec reference

Complete reference for the Texel skin spec (version: 1): structure, colors, layouts (player skins, 57 mob layouts, armor, capes, items, blocks, plants, GUI sprites, particles, paintings), selectors, coordinates, all 18 operations, animation, glow, resource packs and every issue code.

#Shape

{
  "$schema": "https://www.texel.dev.br/schema/skinspec.v1.json",
  "version": 1,
  "name": "Explorer",
  "description": "What this skin should look like (the brief).",
  "model": "classic",
  "palette": { "skin": "#d9a066", "skinShade": "skin:-8", "shirt": "#2f8f83" },
  "legend": { "S": "skin", "s": "skinShade", "W": "#ffffff", "E": "#2d5ba8" },
  "layers": [
    { "op": "fill", "target": "all", "color": "skin" },
    { "op": "fill", "target": "body", "color": "shirt" },
    { "op": "pixels", "target": "head.front", "y": 4, "rows": ["SWESSEWS"] }
  ]
}

#Colors

A color expression is one of:

• #rgb, #rrggbb, #rrggbbaa
• transparent
• a palette key: "shirt"
• any of the above plus :<n>: shift HSL lightness by n points: "shirt:-12", "#88aaff:+6"
• any of the above plus ~<n> (−4…4): a step along a pixel-art tone ramp. Lighter steps also warm toward yellow, darker steps cool toward blue and gain saturation: "cloth~1" (highlight), "cloth~-1" (shadow), "cloth~-2" (deep shadow). On light, saturated pinks and skin tones the darker steps turn vivid red ("#f0b0a8~-2" is #ea5257); shade those with : ("pink:-12") or name a duller shadow color.

Palette entries may reference each other, so a material needs only one base color; derive its tones where you use them ("cloth~-1") or name them:

"palette": { "cloth": "#7a5c3e", "clothLight": "cloth~1", "clothDark": "cloth~-1", "clothDeep": "cloth~-2" }

Base-layer pixels must be opaque (Minecraft renders transparent base pixels black). Overlay pixels are either opaque or transparent. Avoid partial alpha.

#Model anatomy

The character faces you. right/left are the character's own sides: rightArm appears on the viewer's left in the front view.

Every part has two layers: base (the body) and overlay (a slightly larger shell: hat, jacket, sleeves, pants). Overlay starts fully transparent. This section is the player layout; other layouts are listed under Layouts.

#Face-local coordinates

Each operation works in face-local coordinates: (0, 0) is the top-left pixel of the face as seen from outside the model. Drawing is clipped to the face, so it never bleeds into neighbours.

• On front, x grows toward the character's left (viewer's right).
• On right, x=0 is the back edge and the last column touches the front.
• On left, x=0 touches the front and the last column is the back edge.
• On back, x grows toward the character's right.
• On top and bottom, row 0 touches the back, the last row touches the front, and x grows toward the character's left, as seen from above with the front at the bottom.

These hold for every part and layout, lying bodies included. On an animal the front is the head end and the back the rear end, so on a pig body.top and body.bottom both have row 0 at the rump; body.top column 0 runs along the edge of body.right, and its row 0 meets the top row of body.back.

Negative x/y count from the far edge: "y": -2 means "the last 2 rows" when h is omitted.

#Layouts

"layout" picks which texture the spec paints. Everything else works the same: palette, legend, the 17 operations, selectors and face-local coordinates. Each layout has its own part names and texture size; the PNG comes out at that size, ready to drop where the game or the mod expects it.

* marks parts with an @overlay layer. A flat part (items, blocks) only has .front, so "target": "item" is enough.

Notes that save a round:

• Mirrored limbs. In zombie, humanoid, skeleton and enderman the left arm and leg reuse the right ones mirrored in game, so there is only rightArm/rightLeg (or limb) to paint; leftArm is an error with a hint. player and drowned have their own left limbs.
• Lying bodies. The body of a pig, cow, sheep, chicken, wolf or cat (and a wolf's mane, a cold cow's horns, a cat's tail) lies along the animal. Its faces are named the way they face in game, and face-local coordinates read upright as you would see them: body.top is the back (row 0 at the rump, like every top face), body.front the chest, body.back the rump with the tail, body.bottom the belly, and body.right/body.left are 16 wide and 8 tall with the head toward the front. The table gives these boxes as they stand in game, and the review sheet adds a view from above for these layouts. The other ones stand upright: iron_golem and witch read like a player.
• High-level ops. face and hair need an 8×8×8 head (player, zombie, drowned, humanoid, skeleton, creeper, enderman, spider, pig); elsewhere they report op-unsupported, and other heads take pixels. region names (sleeves, boots…) cover the humanoid parts and simply miss elsewhere. lighting and material work on every layout.
• Transparency. Most mobs, cape, painting and the block layouts should be fully opaque, and the review warns about holes. Layouts whose vanilla textures keep transparent pixels on purpose don't: humanoid (armor), skeleton, villager and its overlays, the witch, sheep_wool, illagers, slimes, the translucent allay and vex, shulkers, guardians, item, plant, gui and particle. Parts cut by transparency (a chicken's leg, a fin, a ragged wing tip) are marked in the layout and never count as holes.
• Flat planes and shared pixels. Some mobs have planes with no width (fins, seen from the sides) or no height (a bee's wings, seen from above: the sheet adds a view from above). A few parts share texture pixels in vanilla itself (a bee's antennae, a guardian's fin edges): painting one paints the other there.
• Several files for one mob. Vanilla often splits a mob into several textures with the same layout: enderman_eyes.png, spider_eyes.png, drowned_outer_layer.png, the villager's biome and profession overlays, leather armor's _overlay.png. Write one spec per file, or a family when they share a palette.
• Versions. The layouts follow Java Edition 1.21.x. Bedrock uses the same UVs for most of them, but not for the drowned.
• Bigger textures. item, block and plant take a square size (32×32, 64×64…) for HD packs. Mob textures stay at the vanilla size; scale the PNG up by a whole number afterwards if a pack needs it.
• Glowing parts. enderman_eyes.png, spider_eyes.png, phantom_eyes.png and a mod's <name>_eyes.png are the glowing pixels of a mob on a transparent texture. Mark the ops that paint them with "emissive": true instead of writing a second spec: see Glow.

The CLI lists the same table with node texel.mjs layouts, and node texel.mjs init --layout creeper prints a starter spec. A few layouts are files that start from an empty frame or have no vanilla model; for those, start from init too.

#Selectors

target picks one or more faces:

<parts>[.<faces>][@<layer>]

Join alternatives with +: "head.top+back", "arms+legs.sides". An array of selectors is a union. Whole selectors joined with + are read as a union too: "body.sides+arms.sides" is ["body.sides", "arms.sides"], and "head.front+body" is the face plus the whole body. A layer on the last one ("head.right+head.back@overlay") applies to all of them; a layer on an earlier one only is ambiguous and an error, so write it on each or use an array.

Examples: "all" · "head.front" · "legs.sides" · "body.front+back@overlay" · "arms.top@both".

When a selector matches several faces, the operation runs once per face in that face's local coordinates. {"op":"rect","target":"legs.sides","y":-2,"color":"boots"} paints the bottom two rows all the way around both legs.

#Area options

fill, rect, clear, gradient, pattern, noise, shade and material accept an optional area: x, y (default 0, negatives from the far edge), w, h (default: to the edge). Omit all four for the whole face.

Instead of y/h, a region names the rows. It only paints the parts it belongs to, so "target": "all" is safe, and the hand and shoe regions include the bottom face:

{ "op": "rect", "target": "body.sides", "region": "belt", "color": "leather" }

#Operations

Every op accepts id (string handle for patching), note (free text) and enabled (false skips it).

#fill

Paint whole faces. Like rect, it also takes the area options and region.

{ "op": "fill", "target": "legs", "color": "pants" }

#rect

Paint an area. With only y/h it becomes a band.

{ "op": "rect", "target": "body.sides", "y": 8, "h": 1, "color": "belt" }

#clear

Make an area transparent (overlay only, in practice).

{ "op": "clear", "target": "head.front@overlay", "x": 1, "y": 3, "w": 6, "h": 2 }

#pixels

Pixel art as strings: one string per row, one char per pixel. Chars come from the op's legend, then the top-level legend. . keeps the existing pixel, _ erases it. x/y offset the grid.

{ "op": "pixels", "target": "head.front", "rows": [
  "HHHHHHHH",
  "HhHHHhHH",
  "HSSSSSSH",
  "SDDSSDDS",
  "SWESSEWS",
  "SSSssSSS",
  "SSsMMsSS",
  "SSSSSSSS"
] }

#points

Individual pixels.

{ "op": "points", "target": "body.front", "points": [[3, 8], [4, 8]], "color": "buckle" }

#line

Bresenham line between two points (inclusive).

{ "op": "line", "target": "body.front@overlay", "from": [1, 0], "to": [7, 7], "color": "strap" }

#gradient

Linear blend from → to, vertical (top→bottom, default) or horizontal. steps posterizes into N bands; pixel art usually wants 3–5.

{ "op": "gradient", "target": "legs.sides", "from": "steelLight", "to": "steelDark", "steps": 4 }

#pattern

Repeating pattern: checker (first two colors), stripes-h, stripes-v, diagonal (cycles all colors). size = cell size in px. A color of "." keeps the existing pixel.

{ "op": "pattern", "target": "body", "kind": "checker", "colors": ["steel", "steelDark"] }

#noise

Seeded, deterministic texture. colors + density (0–1, default 0.2) scatters colors; jitter (0–50) randomly shifts the lightness of existing pixels by ±jitter points. Use either or both. seed defaults to the layer index.

{ "op": "noise", "target": "body.sides", "jitter": 4, "seed": 3 }

#shade

Shift lightness of existing pixels by amount (−100…100), with the hue drift of a ~ step: darker turns slightly cooler, lighter slightly warmer (grays stay gray). The workhorse for depth.

{ "op": "shade", "target": "rightLeg.left+back", "amount": -7 }

#copy

Copy one face (from must select exactly one) onto target faces. flip: h, v, hv. Sizes are resampled if they differ. Works on @overlay faces too, which is how a feature that spans several faces stays symmetric: paint one arm's part of a pair of wings, copy it to the other arm flipped, and symmetrize the part on the body.

{ "op": "copy", "from": "head.right", "to": "head.left", "flip": "h" }
{ "op": "copy", "from": "leftArm.back@overlay", "to": "rightArm.back@overlay", "flip": "h" }

#mirror

Mirror a whole part onto another (left/right faces swap, everything flips horizontally). layer: base, overlay, both (default).

{ "op": "mirror", "from": "rightArm", "to": "leftArm" }

#symmetrize

Make faces left-right symmetric by copying one half onto the other. source: left (default, low x) or right.

{ "op": "symmetrize", "target": "head.front" }

#High-level operations

These do the craft from the art guide for you: face layout, hair that wraps around the head, material texture, light from above. Use them for the broad strokes, then add personality with pixels, points and line. They are ordinary layers: later layers still paint over them.

#material

Fill an area with a color and the texture of a material, with its tones derived from that one color. kind: plain, skin, fabric, knit, leather, metal, fur, stone, scales, wood, glow. Takes the area options and region; seed varies the grain. fur has strong grain and turns blotchy on very light colors (white or pastel coats, and feathers, which are read as fur); use skin or plain plus noise with jitter 2–4 there.

{ "op": "material", "target": "legs", "region": "boots", "color": "#4a3324", "kind": "leather" }

#face

A complete 8×8 face on head.front (or target): brows on row 3, eyes on row 4, nose, mouth on row 6. Needs skin and eyes (iris color). Optional:

{ "op": "face", "skin": "skin", "eyes": "#3a6fd9", "eyeStyle": "cute", "mouth": "smile", "blush": true }

#hair

Hair on the whole head, wrapping the top, back and sides, with volume on the overlay. style: short (default), buzz, bob, long, spiky, curly, ponytail, mohawk. fringe: side (default), full, parted, none. layer: both (default), base, overlay. Put it after face, since the fringe covers the top rows.

{ "op": "hair", "color": "#6b3e1f", "style": "ponytail", "fringe": "full" }

#lighting

Light from above and slightly in front, the way the art guide shades by hand: tops lighter, bottom rows and bottoms darker, backs and the inner faces of limbs darker. With no target it lights everything except head.front (the face, on mobs too). strength scales it (default 1, 0–3). Like shade, it cools what it darkens and warms what it lights. Put it after the broad fills and before small details, so buttons and eyes keep their exact colors.

{ "op": "lighting" }

#bevel

A frame in the vanilla GUI style over the target area (the whole face, or x/y/w/h): style raised (default: light along the top and left, dark along the bottom and right) or inset (the reverse, like an inventory slot), depth rings (1–8, default 1), and an optional outline around it with its four corner pixels left out, like vanilla's rounded buttons and panels. light and dark default to color lightened and darkened. The inside is filled with color. Works on any flat face; made for gui sprites.

{ "op": "bevel", "target": "sprite", "color": "#c6c6c6", "light": "#ffffff", "dark": "#555555", "outline": "#000000" }

#Glow

"emissive": true on any op makes the pixels it paints glow: they also go to a second texture, <name>_eyes.png, transparent everywhere else, the way vanilla draws spider_eyes.png and enderman_eyes.png and mods draw glowing eyes. On face only the eyes glow. A later op that paints over a glowing pixel turns it off unless it is emissive too; shade, noise and lighting adjust it and keep the glow; copy, mirror and symmetrize carry it along. The review counts the glowing pixels and the sheet shows them on black.

{ "op": "face", "skin": "skin", "eyes": "#5ff3ff", "eyeStyle": "glow", "emissive": true }

#Animation

Items, blocks, plants, GUI sprites and particles can animate. animation.frames lists the frames; each is a patch over the spec's layers (by id), so a frame says only what changes, and {} is the spec as it is. frametime (ticks per frame, 20 per second, default 1), interpolate (blend between frames) and a frame's own time go to the .png.mcmeta.

"animation": {
  "frametime": 4,
  "frames": [
    {},
    { "patch": [{ "do": "update", "id": "embers", "set": { "seed": 2 } }] },
    { "patch": [{ "do": "palette", "set": { "glow": "#ffb43a" } }], "time": 8 }
  ]
}

The texture compiles to a vertical strip of its distinct frames: a frame repeated later is stored once and listed by index in the .png.mcmeta, as vanilla does. A particle compiles to one file per frame instead (<name>_0.png, <name>_1.png…), listed by its particle definition. The layers themselves are frame 0 for everything else (the review, the views); the sheet adds every frame. The review warns when all frames are the same picture. Animating a mob texture is ignored: the game draws it still.

#GUI sprites

The gui layout is any size: a button is "size": [200, 20], a slot [18, 18], a whole container screen [256, 256] with "asset": "gui/container/furnace". The default place in a pack is gui/sprites/<name>; set asset to replace a vanilla sprite, such as gui/sprites/widget/button.

gui.scaling tells the game how to draw the sprite at other sizes, and goes to its .png.mcmeta:

width and height default to the texture size. Borders must leave a middle. The sheet shows the sprite drawn at two other sizes the way the game resizes it, so a gradient that breaks when tiled shows right away. The bevel op draws the raised and inset frames vanilla uses.

#Blocks and tiling

block is one texture on every side (cube_all). block_column (logs, pillars: side and end), block_bottom_top (grass, sandstone: side, top, bottom) and block_orientable (furnaces: front, side, top) paint every texture of a block in one spec and come out as one file per part, named the vanilla way: oak_log.png and oak_log_top.png, sandstone_side.png, furnace_front.png. plant is a cross block's texture (flowers, saplings, crops), with a transparent background.

Blocks sit next to copies of themselves, so the review measures each part's seams: how much more the colors jump across the edge where two copies meet than between neighbors inside the texture (stats.seams, 1 = seamless). Over 2.5 it reports tile-seam with the part. The sheet shows every part tiled 3×3 and the block in 3D.

#Resource packs

node texel.mjs pack (or the MCP tool texel_pack) builds a resource pack from specs, families and folders of specs: a folder, or a .zip the game loads as is. Each texture goes to assets/<namespace>/textures/<asset>.png with every file it compiles to (block parts, animation strip and .png.mcmeta, particle frames, _eyes), and pack.mcmeta gets the format of --mc-version (1.21 to 1.21.11; the default is the latest).

Where each texture goes: the spec's asset; otherwise its layout's default, the vanilla texture for mobs (entity/pig/temperate_pig: a pack replaces it) or item/<name>, block/<name>, particle/<name>, gui/sprites/<name>, painting/<name> from the file name. --namespace mymod puts textures without one in a mod's namespace; --models also writes what a new item or block needs: the models (item/generated, or item/handheld for an item named like a tool or weapon, such as ruby_sword or iron_hammer, so it is held diagonally; cube_all, cube_column, cube_bottom_top, orientable, cross), a block state, and from 1.21.4 the item definition. A particle gets its particles/<name>.json. A mod also needs its names in assets/<namespace>/lang/en_us.json ("item.mymod.ruby_sword": "Ruby Sword"); the pack doesn't write them, so the game shows the raw keys until the mod or the pack has them.

node texel.mjs check-pack <folder|zip> (texel_check_pack) checks any pack, not only Texel's: pack.mcmeta and the versions its format covers, file and namespace names the game would skip, PNGs, .mcmeta animations and GUI scaling, entity textures against the size of their Texel layout, models, block states, item definitions and particles that point at missing files, and textures nothing uses. Each issue has the file, a JSON path and a hint; codes are in the table below.

#Importing a picture

node texel.mjs import picture.png --layout item --pixelize (or texel_import_png with pixelize: true) turns concept art, a render on a white background or an HD skin into an editable spec: a flat background is removed, the subject is cropped and scaled to the layout's size (averaging, so an HD skin halves exactly), colors are reduced (--colors, default 16), lone specks cleaned, and --outline auto draws a dark 1-pixel outline like vanilla items. Mob and skin layouts are scaled whole, keeping their UVs. Then the usual import: one layer per face, palette keys c01… to rename.

#Patches

To change an existing spec, send only what changes. Layers are addressed by id, so give every layer you may revisit one (withIds in /texel-core.mjs adds "<op>-<index>" ids to the rest). Entries apply in order; one that can't apply (unknown id) is skipped and reported, and the others still apply.

Apply one with node texel.mjs patch skin.json fix.json -o skin.json, the MCP tool texel_patch or window.texel.applyPatch(patch) in the studio. They add the <op>-<index> ids before patching and keep them in the result, so the next patch can use the same ids.

{ "patch": [
  { "do": "update", "id": "face", "set": { "eyeStyle": "wide", "mouth": "smile" } },
  { "do": "replace", "id": "hood", "layer": { "op": "fill", "target": "head.top+back@overlay", "color": "robe~-1" } },
  { "do": "add", "after": "belt", "layer": { "op": "points", "target": "body.front", "points": [[3, 8], [4, 8]], "color": "gold" } },
  { "do": "remove", "id": "noise-12" },
  { "do": "palette", "set": { "robe": "#2f4fb0" } },
  { "do": "meta", "set": { "description": "Now with a gold buckle." } }
] }

#Texture map (for importing / debugging)

UV origin of each box in the 64×64 player skin PNG (other layouts list their boxes in Layouts; node texel.mjs layouts prints them). Within a box of size w×h×d at (u, v): top (u+d, v), bottom (u+d+w, v), right (u, v+d), front (u+d, v+d), left (u+d+w, v+d), back (u+2d+w, v+d).

#Review issue codes

Every issue has a code, stable across releases, a level (error: the op or file is skipped; warning: it works but shows; info: worth a look), a JSON path and usually a hint.

Compiling a spec

Review

Patches

Families

Building a resource pack

Checking a resource pack

CLI exit codes

Score = 100 − 25 per error − 8 per warning − 2 per info (transparent-base penalty capped at 20). Craft advice (art.advice: pillow-shading, unshifted-shadows, confetti-noise, edge-mismatch) never changes a score.