rev2d

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

English · 한국어

▶ Watch the 1-minute demo · 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 19-command CLI with --json output, atomic and validated edit operations, and an MCP server with 16 tools that return renders as images. The whole workflow is in How AI agents use Rev2D.

• 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.

Related MCP server: unreal-animation-mcp

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:

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).

$ 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.

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.

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

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

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 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.

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:

$ 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.

The editor

rev2d edit opens a web editor (React 19 + WebGL2) at http://127.0.0.1:4777. It evaluates models with the same core as the CLI.

Press ? in the editor for every shortcut.

Live2D and Spine concepts in Rev2D

Format details: docs/SPEC.md. Which example uses which technique: examples/README.md.

Quick start

Requirements: Node 22+ and git.

git clone https://github.com/RevStudio/Rev2D.git && cd Rev2D
npm install

node bin/rev2d.js new hero.r2d.json --template hana     # templates: blank (default), empty, minimal, hana, robot-arm, slime, textured
node bin/rev2d.js validate hero.r2d.json
node bin/rev2d.js render hero.r2d.json -o out/hero.png --overlay bones,warps,labels
node bin/rev2d.js sheet hero.r2d.json -o out/params.png --overview --scale 0.25
node bin/rev2d.js sheet hero.r2d.json -o out/turn.png --sweep AngleX=-30:30:3 --sweep AngleY=30,0,-30 --scale 0.5
node bin/rev2d.js analyze hero.r2d.json --anim idle --warmup 8
node bin/rev2d.js edit hero.r2d.json                    # live editor at http://127.0.0.1:4777

In a checkout the CLI runs the TypeScript sources directly (no build step). The editor UI is served from dist/editor after npm run editor:build, or compiled on the fly by Vite when there is no build. If port 4777 is taken, add --port 0 to pick a free one. rev2d help <command> lists every flag, and docs/CLI.md documents every command and its --json output.

Conventions. Coordinates are canvas pixels with the origin top-left and +y down. Angles are degrees, positive = clockwise. Standard parameters follow Live2D names and signs: AngleX > 0 turns toward the screen right, AngleY > 0 looks up, and L in an id means the character's left, which is on the screen right.

Examples

Five models ship as templates (rev2d new my.r2d.json --template <name>). All images below are CLI output.

textured (the koinobori in the demo) shows PNG atlas crops bent by warps, a textured mesh with UVs and a texture-alpha mask. Details and a feature matrix: examples/README.md.

Documentation

The tool serves the same docs offline: rev2d docs <spec|ops|cli|mcp|agents|recipes|architecture|examples>, or MCP rev2d_docs.

Status and roadmap

Rev2D is at v0.1. The format (version 1), the CLI, the MCP tools and the editor work and are covered by 1,350+ tests, but they may still change before 1.0. There is no npm release yet: run it from a checkout.

Rev2D does not replace Live2D Cubism or Spine for production pipelines. It is a text-first toolkit for AI-assisted authoring and experiments. Some ideas we may explore (not promises):

• Importing layered artwork (PSD / Photoshop) as parts

• Runtimes for game engines and the web (Unity, Godot, a small web player)

• Audio-driven lip-sync for mouth parameters

• More constraints: longer IK chains, transform and path constraints

Ideas and use cases are welcome in the issues.

Development

npm test                    # the full vitest suite (1,350+ tests)
npm run typecheck           # tsc --noEmit -p tsconfig.json
npm run editor:dev          # editor UI with hot reload; proxies /api to rev2d edit on :4777
npm run editor:build        # build the editor UI into dist/editor (served by rev2d edit)
npm run build               # compile src/ to dist/ and build the editor UI (what the package ships)
npx tsx scripts/build-examples.ts   # regenerate examples/ from their builders

The editor end-to-end tests use playwright-core with an installed Google Chrome. They skip, with a reason, when the UI is not built or Chrome is missing.

Demo media. Everything in docs/media is generated from real CLI output, real renders and screen recordings of the real editor:

node scripts/video/capture-all.mjs   # capture: CLI transcripts, frame sequences, editor recordings -> out/video/assets
node scripts/video/compose.mjs       # compose: docs/media/*.mp4, hero.gif, ai-live-edit.gif, poster.png, verify.png

This needs Google Chrome and ffmpeg/ffprobe on the PATH (on Windows you can instead set FFMPEG_DIR to the folder with ffmpeg.exe). The capture step starts its editors on free ports with a sandboxed home directory.

Contributing

Issues and pull requests are welcome. Before you open a PR, run npm test, npm run typecheck and, if you touched editor/, npm run editor:build. The docs are tested too: links, command lines and recipes are checked by the suite. Module boundaries and where to add a feature are described in AGENTS.md, Part 2.

License

MIT © 2026 RevStudio