Inside the .mavatar File Format

Every Mesh Avatar Studio avatar exists as a project folder while you work and as a single .mavatar archive when you share it. Understanding the layout helps with troubleshooting, backup and building tools on top.

The project folder

projects/<name>/
├── source.png        # your illustration, untouched
├── rig.json          # the skeleton (see the rig fields reference)
└── built/            # generated layers and metadata
    ├── base.png          # artwork minus cut-out layers
    ├── hairmask.png      # inferred hair mask
    ├── eye0_*.png …      # per-eye ball/lash/low/crease layers
    ├── layers.json       # layer metadata
    ├── sprites/          # drawn variants (closed eyes, mouths…)
    └── overlays/         # glasses and similar overlay layers

The folder is created by the agent tooling (tools/new-project.py) and never committed to version control. source.png plus rig.json fully determine the build: delete built/ and you can regenerate it.

What the builder writes

• rig.json gains the generated eye edge samples (x0/x1/top/bot — 24 points per curve).
• Layer images are cut guided by the rig: hair mask from the traced strand/bun areas, eye layers from the opening polygons, hand and accessory layers only when the rig has them.
• Drawn variants you or an image generator produced are preserved across rebuilds.

The .mavatar archive

Export .mavatar in the editor packs one file containing:

• the manifest (avatar.json) — metadata, saved lip-sync settings, provenance;
• built layers and their metadata (layers.json);
• sprite metadata for drawn eye/mouth variants;
• overlay metadata for glasses-type layers;
• optionally the source image (default on — without it the avatar can play but not be edited or rebuilt).

Imports accept archives up to 128 MiB and create a fresh project under projects/, renaming on collision.

Compatibility and validation

The format documents archive rules and compatibility guarantees — runtimes validate manifests and layer metadata on load, and the repository ships tooling to pack and validate whole folders (useful in CI or before sharing). The avatar element and the mesh-avatar npm package both load the same artifacts, and the experimental native (Rust) runtime reads the same .mavatar files and built folders as the JavaScript runtime.

Practical notes

• Backup: a .mavatar with source included is a complete backup — everything else is regenerable.
• Sharing for play only: export without the source for a smaller file; recipients can still run it in the browser Player.
• Streaming from a URL: the stream view accepts an avatar parameter pointing to a .mavatar on the same origin as your local server.
• Editing metadata by hand: possible but unnecessary — the editor and export flow keep the manifest consistent.

The authoritative spec — every file, field and compatibility rule — is the official format documentation.