Rev2D
**Live2D/Spine-style 2D rigging & animation — built for AI agents**
**English** · [한국어](README.ko.md)
[](LICENSE)
[](docs/MCP.md)
**[▶ Watch the 1-minute demo](docs/media/rev2d-demo.mp4)** · English headlines, Korean captions
## What is Rev2D?
- **A rig is one JSON file.** Parameters, bones, warp deformers, parts, keyform bindings, IK,
physics and layered animations live in one `*.r2d.json`, addressed by id, in canvas pixels. You
can diff it, review it and generate it.
- **A deterministic, headless renderer.** Pure TypeScript with no GPU and no browser: the same
model and inputs always give the same pixels. It renders debug overlays, contact sheets, GIFs and
PNG sequences.
- **Tools an agent can drive.** A 35-command CLI with `--json` output, atomic and validated edit
operations, and an MCP server with 18 tools that return renders as images. The whole workflow is
in [How AI agents use Rev2D](#how-ai-agents-use-rev2d).
- **An avatar from one illustration.** Give it one picture: landmarks placed by an agent (or by
you, with handles) turn it into a model that blinks, talks, turns its head, breathes and sways its
hair. See [Avatar from one illustration](#avatar-from-one-illustration).
- **Spine and Live2D files in and out.** Spine skeletons import as models and models export to
Spine runtimes; Live2D motions, expressions and physics move both ways. See
[Spine and Live2D interop](#spine-and-live2d-interop).
- **A live editor for the human.** A React + WebGL2 [editor](#the-editor) reloads every change the
AI writes, and the AI can see and drive the view you are looking at. It can also run Codex or
Claude Code itself, in its [AI panel](#the-ai-panel).
## How AI agents use Rev2D
Rigging tools are built for a mouse and a pair of eyes. Rev2D keeps the concepts of Live2D and
Spine and makes each step readable, writable and checkable by a program, so an agent can build a
rig and **prove** it works before it says it is done.
In one line: **write the JSON, check it with renders and numbers, fix it with ops, check again.** No
human has to look at the pixels for it: the agent sees its results in renders and sheets and
measures them with `inspect` and `analyze`.
An agent connects in one of three ways:
| Way in | Use it for | Start here |
| --- | --- | --- |
| **MCP server** | Claude Code, Claude Desktop and other MCP clients | [Connect Claude Code](#connect-claude-code-or-any-mcp-client), 18 tools |
| **CLI** | Any agent with a shell | `--json` on every command; the guide is [AGENTS.md](AGENTS.md) |
| **Editor bridge** | Working together while a human watches in the editor | `rev2d edit`, then `rev2d editor ...` commands or the MCP `rev2d_editor_*` tools |
### The loop
```text
┌──► validate ──► render ──► sheet ──► inspect / analyze ──┐
│ pointers overlays sweeps exact numbers: │
│ + hints + notes overview IK, physics, seams │
└───────────────── fix with atomic ops ◄────────────────────┘
```
Examples below write `rev2d` for `node bin/rev2d.js` (or `npx rev2d` inside the checkout).
| Step | CLI | MCP tool | What the agent gets |
| --- | --- | --- | --- |
| 1. Author | `rev2d new hero.r2d.json --template hana`, or write the JSON directly | `rev2d_create_model` | a valid starting rig (blank, empty or one of 5 examples) |
| 2. Validate | `rev2d validate hero.r2d.json --json` | `rev2d_validate` | every problem with a JSON pointer, a stable code and a fix hint |
| 3. Look | `rev2d render hero.r2d.json -o out/look.png --overlay bones,warps,labels,grid` | `rev2d_render` | a PNG, plus notes when something looks wrong (IK out of reach, physics clamped, parts off-canvas) |
| 4. Sweep | `rev2d sheet hero.r2d.json -o out/turn.png --sweep AngleX=-30:30:3 --sweep AngleY=30,0,-30` (or `--overview`, `--anim idle`) | `rev2d_sheet` | a parameter range, every parameter, or an animation in one captioned image |
| 5. Measure | `rev2d inspect hero.r2d.json --param AngleX=30 --part mouth --json`, `rev2d analyze hero.r2d.json --anim idle --warmup 8` | `rev2d_inspect`, `rev2d_analyze` | bone transforms, part bounds, IK reach, physics clamping and loop seams as numbers |
| 6. Fix | `rev2d ops hero.r2d.json edits.json --dry-run`, then without `--dry-run` | `rev2d_apply_ops` | a per-op report; nothing is written unless the whole batch applies and validates |
The human opens the editor; the agent edits the file and drives the view from its own terminal (or
over MCP). These are the commands from the demo:
```sh
# the human
rev2d edit hero.r2d.json # http://127.0.0.1:4777
# the agent
rev2d ops hero.r2d.json --op '{"op":"recolor","parts":["hairBack","hairBackStrands","hairSideR","hairSideStrandR","hairSideL","hairSideStrandL","hairFront","hairFrontStrands","hairFrontShine"],"hsl":{"h":-120,"s":0.25,"l":0.05}}'
rev2d editor command --params AngleX=25,EyeLOpen=0,MouthOpen=0.6
rev2d editor command --play talk
rev2d editor screenshot -o out/seen.png # a render of exactly what the human sees
rev2d editor state # open model, parameters, time, layers, selection, view
rev2d editor command --message "Hair is teal now, pose set, talk played."
rev2d editor command --open models/cat.r2d.json # switch the editor to another model in its workspace
```
- **The AI sees** what you see: `editor state` (parameters including the editor's own physics
results and the sliders you pinned, time, animation layers, selection, visible region) and
`editor screenshot` (rendered by the same renderer as `rev2d render`).
- **The AI drives** the view: parameters, play / pause / seek, animation layers, selection,
overlays, focus, messages, and which file is open.
- **No lost edits.** If the agent writes the file while you have unsaved edits, your next save is
refused (HTTP 409) and you choose to reload its version or overwrite it.
### Try these prompts
> Make a cat mascot with rev2d: a head turn, a blink and tail physics. Verify it with sheets and
> `analyze`.
> Create `cat.r2d.json` from the blank template and give it a blink: an `EyeOpen` parameter bound
> to the eye, and a 0.4 s `blink` animation. Before you say it's done, show me a sweep sheet, an
> animation sheet and the `inspect` numbers for the closed eye.
> I have the editor open on `hana.r2d.json`. Make her hair teal, turn her head to AngleX 25 and
> play `talk` so I can watch, then take a screenshot of what I see and tell me what changed.
> Put a small hat on hana that stays on her head when she turns (use the `follow` op). Prove it
> with an AngleX × AngleY sheet and `inspect --point` numbers for the hat's anchor.
> Analyze every animation in `robot-arm.r2d.json` for IK reach, physics clamping and loop seams.
> Fix what you find with ops, and show me before/after sheets.
> Turn `my-character.png` into an avatar with the `rev2d avatar ...` commands (read `rev2d docs avatar` first).
> Show me the review sheets and tell me which landmarks you are least sure about.
### Why it works
**Diagnostics an agent can act on.** Each problem names the exact place in the file, a stable code
and the fix. This is real output for a model with two typos:
```console
$ rev2d validate blob.r2d.json
FAIL blob.r2d.json
error /parts/0/parent unknown-parent unknown parent "bodyWarpp" (must be a bone or warp id) → did you mean "bodyWarp"?
error /bindings/1/target invalid-target bone has no property "scaleYY" → did you mean "scaleY"?
2 errors, 0 warnings
```
**Deterministic renders.** No GPU, no browser, no clock, no randomness: the same model and inputs
give byte-identical PNGs and GIFs (the test suite checks this). A before/after `rev2d diff` means
something, and a render is evidence rather than a guess.
**Numbers, not just pixels.** Looking is expensive and vague; numbers are cheap and exact.
`AngleX > 0` should turn the face toward the screen right, and `inspect` confirms it: at
`--param AngleX=30` the mouth center of the hana example moves from `[256, 321.9]` to
`[286.9, 322]`. `analyze` reads a whole animation without watching it. On hana's idle loop it
reports that no hair physics output is ever clamped, that the loop seam is 0% different, and which
parts leave the canvas.
## Avatar from one illustration
Rigging a character usually starts with a layered drawing. Rev2D can also start from **one flat
picture**, ideally a front-facing bust on a transparent background. Someone places landmarks on it
(the head, the eyes, the mouth, the hair strands, the body), and Rev2D cuts the picture into layers
along them, fills in what was behind each layer, and generates an ordinary Rev2D model. The model
blinks, talks, turns and tilts its head, breathes and sways its hair, and it comes with physics,
six animations (`idle`, `blink`, `talk`, `nod`, `look_around`, `sweep`) and review sheets.
