The rig.json file is the skeleton of every Mesh Avatar Studio avatar: it tells the engine where the head, eyes, mouth, hair and body are in your illustration and how far each may move. The editor edits this file when you drag dots; agents draft it from zoomed grids; the layer builder consumes it. This reference explains the coordinate system and every field group.
The coordinate system (read this first)
- Origin at the top-left of
source.png, x right, y down. - Coordinates, radii, lengths and bands are in source pixels; angles are radians — not the degrees used by the pose sliders.
- All numbers must be finite; ellipse radii and mesh cell sizes positive; mesh cell sizes and fine-mesh rectangle coordinates integers.
- A
bandis[start, end]with start < end: a Y range where an influence fades from full to zero. - Ellipses are smooth influence regions, not hard cut-outs — a big head ellipse will not crop your artwork, it decides how motion spreads.
Only buns, strands, accessories, hand, view.gazeCenter and view.irisTravel are optional — omit what the illustration does not have. Never copy the sample avatar's coordinates into a new image.
head — the face-turn engine
| Field | Meaning |
|---|---|
cx, cy, rx, ry | Influence ellipse: centre near the face centre, slightly above the eyes; radii must include hair and head accessories, avoiding shoulders where possible |
shiftX / shiftY | Max face-turn displacement; start around 3–4% / 2–3% of image size |
pivotX, pivotY | Roll pivot — the centre of the neck, above the collarbone |
maxRoll | Roll magnitude at a ±30° pose in radians; start near 0.15 |
weightBand / turnBand | Y ranges fading head influence and face-turn displacement below the chin |
body — breathing and sway
Roll pivot near the bottom of the image (maxRoll around 0.035 for a ±10° pose), a chest ellipse covering the visible upper torso inside the arms, one ellipse per visible shoulder, and three bands: breathBand (breathing fades from upper chest down), rollBand (body roll fading to the anchored lower torso), plus the head bands above.
face — small influence ellipses
One ellipse each for nose, mouth, both eyes (eyeA = image-left), both ears (placed even when hidden under hair), a brow ellipse with a fade band, and a jaw ellipse above the chin. These decide how localized mesh deformation is around each feature.
eyes — the polygons that make blinking work
| Field | Meaning |
|---|---|
opening | Polygon tracing the eye white + iris inside the lashes, 14–20 points starting at the outer corner — the quality of blinking lives here |
roi | Polygon surrounding the full lashes and lower lid by about 10–20 px, avoiding hair |
x0, x1, top, bot | Generated by the builder (24 sampled edge points) — omit all four in drafts or supply all four; partial groups are errors |
Index 0 is the image-left eye. Changing eye geometry always requires a layer rebuild — old sampled curves cannot reconstruct new pixels.
mouth — a line plus an edit area
The closed mouth is described as a line: centre, angle, half-length and a bow curvature (px at the middle). A separate rotated area ellipse slightly beyond the lip corners is the edit region for drawn open-mouth sprites — tall enough for open mouths without reaching the chin.
strands — swaying hair physics
Each lock is a root-to-tip polyline (nodes, starting with four points entirely on hair), an influence width (sigma ≈ half the visible lock), a spring multiplier (k, start 1) and a max displacement (max, 7–12 px). Bangs: 3–5 locks; side hair: two per side.
Optional groups
buns— one ellipse per hair bun, excluding ribbons.accessories— hanging tassels/earrings: a pivot (attachment), tip, a two-bone split fraction (~0.4), a search box and red-dominance colour thresholds (the builder currently isolates red accessories).hand— a full outline to cut the hand out, jaw polylines to reconstruct what it hides, elbow/wrist/knuckle pivots, a fingertip contact pinned near the chin, and six fade bands. Powerful and fiddly — see the official table.cloth/legs/arms— experimental full-body groups: garment outlines with waist/hem attachment (optionally seams and tiers for ruffle physics), planted legs with weight shift, hanging arms with split lines.
mesh — deformation resolution
Cell sizes control mesh density: baseCell (~14), a fine rectangle around face and hair with a finer cell (~7), and dedicated cells for hand (~9), tassels (~6), eye white (~4), lash (~3) and sprite (~4) layers. Reduce fine cells only when detail needs it. view holds viewport margins and the optional gazeCenter / irisTravel for pointer-following eyes (raise to ~15% of eye width for large eyes).
How this file is actually edited
In practice you almost never hand-edit: the editor's draggable dots write these fields, and coding agents draft them from zoomed coordinate grids following the official agent guide. Hand-editing matters when you script batches or debug a specific number. The complete field table, including every band and experimental group, lives in the official rig fields documentation.