Rev2D

<!-- Maintainers: Demo video: GitHub plays an MP4 inline only when it is uploaded as an attachment, not when it is linked from the repository. Edit this README on github.com, drag docs/media/rev2d-demo.mp4 (65 s, 5 MB) into the editor and wait for the upload: GitHub inserts a https://github.com/user-attachments/assets/<id> URL. Put that URL on its own line right below the poster link (a bare attachment URL on its own line renders as a video player). --> <div align="center"> <h1>Rev2D</h1>

Live2D/Spine-style 2D rigging & animation — built for AI agents

English · 한국어

<img src="docs/media/hero.gif" width="720" alt="Four Rev2D example models animating in a 2x2 grid: hana, an anime bust, idling and blinking; a slime jumping; a robot arm reaching with IK; textured koinobori fluttering on a pole">

<a href="docs/media/rev2d-demo.mp4"><img src="docs/media/poster.png" width="480" alt="Rev2D demo video poster: Live2D/Spine-style 2D rigging, built for AI agents. Click to watch the 1-minute demo"></a>

▶ Watch the 1-minute demo · English headlines, Korean captions

</div>

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.
• 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.
• 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.
• A live editor for the human. A React + WebGL2 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.

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, 18 tools | | CLI | Any agent with a shell | --json on every command; the guide is 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

  ┌──► 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 |

<details> <summary><b>A full loop, verbatim</b>: giving the blank template a blink</summary>

$ node bin/rev2d.js new blob.r2d.json
created blob.r2d.json from template "blank" (512x512; 0 errors, 0 warnings)

$ node bin/rev2d.js ops blob.r2d.json --op '{"op":"add","kind":"parameter","value":{"id":"EyeOpen","min":0,"max":1,"default":1}}' --op '{"op":"bind","target":"part:eye.shape.ry","params":["EyeOpen"],"keys":[{"at":[0],"value":2},{"at":[1],"value":26}]}'
applied 2 ops on blob.r2d.json
  ok  #0  --op #1  add   added parameter "EyeOpen" as /parameters/2 (range 0..1, default 1)
  ok  #1  --op #2  bind  added binding part:eye.shape.ry ← [EyeOpen] as /bindings/3 (2 keyforms)
wrote blob.r2d.json

$ node bin/rev2d.js validate blob.r2d.json
ok    blob.r2d.json  (0 errors, 0 warnings)

$ node bin/rev2d.js sheet blob.r2d.json -o out/blink.png --sweep EyeOpen=0:1:3 --sweep Lean=-1,0,1 --scale 0.5
wrote out/blink.png (800x848, 9 cells, 3 per row, cell viewBox 0,0,512,512, scale 0.5)
cells: EyeOpen=0,0.5,1 x Lean=-1,0,1

$ node bin/rev2d.js inspect blob.r2d.json --param EyeOpen=0 --part eye --json
{
  "time": 0,
  "params": { "Lean": 0, "Squash": 0, "EyeOpen": 0 },
  "drawOrder": ["body", "eye"],
  "properties": { "part:eye.shape.ry": 2 },
  "events": [],
  "ik": [],
  "physics": [],
  "parts": [
    {
      "id": "eye",
      "visible": true,
      "opacity": 1,
      "z": 1,
      "bounds": [241, 235, 30, 4],
      "center": [256, 237]
    }
  ]
}

$ node bin/rev2d.js analyze blob.r2d.json --anim idle
analysis of idle (2s loop): 120 frames over t=0..2s

PARAMETERS (min..max over the frames, [range])
  Lean  -0.5..0.5  [-1..1]
  Squash  0..0.4  [0..1]  reaches min
  constant: EyeOpen=1

LOOP SEAM (end of the loop extrapolated to t=2 vs t=0)
  parameters and bones close the loop
  pixels: 0% differ between t=0 and one loop later (threshold 8, max delta 0)

BOUNDS
  visible parts over all frames: [112.9, 126.5, 286.2, 259] (canvas 512x512)

The closed eye is 4 px tall (bounds is x, y, w, h), the sweep sheet shows it at every lean, and the idle loop closes. Only the "next steps" lines that new prints are left out.

</details>

Connect Claude Code (or any MCP client)

claude mcp add rev2d -- node /absolute/path/to/Rev2D/bin/rev2d.js mcp

Add --scope project to share it through the project's .mcp.json:

{
  "mcpServers": {
    "rev2d": {
      "command": "node",
      "args": ["/absolute/path/to/Rev2D/bin/rev2d.js", "mcp"]
    }
  }
}

Any client that starts stdio servers (Claude Desktop, other MCP clients) uses the same command. On Windows, write the path with forward slashes (C:/Users/me/Rev2D/bin/rev2d.js). Ask the agent to call rev2d_guide first. Without MCP, any agent with a shell can drive the CLI instead: every command has --json, and AGENTS.md is the agent's guide.

| Group | Tool | Purpose | | --- | --- | --- | | Learn | rev2d_guide | Quickstart for AI authors: conventions, workflow, address grammar, recipes. Call first. | | | rev2d_schema | JSON Schema of the model, or of one part of it (Part, Binding, Physics, ...) | | | rev2d_docs | The bundled docs: spec, ops, cli, mcp, recipes, interop, avatar, architecture, examples, agents | | Check | rev2d_validate | Diagnostics with JSON pointers, stable codes and fix hints | | | rev2d_info | Outline: parameters and what they drive, bone tree, warps, parts, bindings, IK, physics, animations | | See | rev2d_render | One pose as an inline PNG, with overlays, IK reach and warning notes | | | rev2d_sheet | One captioned grid: an animation over time, 1–2 parameter sweeps, or an overview of every parameter | | | rev2d_diff_images | Pixel diff of two PNGs, with the differences drawn in red | | Measure | rev2d_inspect | Exact numbers for a pose or a series of times: bones, part bounds, IK, physics, mapped points, track tables | | | rev2d_analyze | A whole animation checked at 60 fps: ranges, physics clamping, IK snap risk, events, loop seam | | | rev2d_hit_test | Which parts cover a canvas point, top-most first | | Edit | rev2d_apply_ops | Atomic, validated edits by id (16 ops: add, bind, bind_warp, follow, recolor, compose, ...) | | | rev2d_create_model | A new model from blank, empty or an example template | | Editor bridge | rev2d_editor_state | What the human sees: open model, workspace, pose, time, layers, selection, view | | | rev2d_editor_command | Drive the editor: open a file, set parameters, play, seek, select, overlays, focus, message | | | rev2d_editor_screenshot | A PNG of exactly what the human sees |

Arguments and results for every tool: docs/MCP.md.

The live editor bridge: the AI works in the window you are watching

<img src="docs/media/ai-live-edit.gif" width="800" alt="Left: a terminal where an AI runs real rev2d commands (validate, info, a recolor op, editor command, editor screenshot). Right: the Rev2D editor open in Chrome reloads with teal hair, turns the head, plays the talk animation and shows the AI's message">

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:

# 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 `ed