# rig-c — Complete Toolchain Documentation (llms-full.txt) > Source: https://rig-c.org/llms-full.txt > Generated: 2026-10-19 > Purpose: Single-request Markdown bundle of all documentation pages on https://rig-c.org for AI agents, RAG pipelines, and curl inspection. ================================================================================ URL: https://rig-c.org/ Markdown: https://rig-c.org/index.md Package: rig-c@2.61.0 Repository: https://github.com/rig-c ================================================================================ # rig-c — AI-Authored 2D Rigging and Animation, Verified Before It Is Written One character painting goes in; a rigged, animated 2D character that plays in the browser or imports into the Spine 4.3 editor comes out. Every stage prints named, numeric findings and refuses by name what it cannot verify, so a broken file never reaches the disk. **rig-c makes no images.** The painting and its layer split ([See-through](https://github.com/shitagaki-lab/see-through)) come from image models you run yourself — on your own GPU, or a free web demo. rig-c starts from those files, ships no model weights, and runs every one of its own steps on the CPU. ## From loose parts to a living rig
Loose part PNGs assembling themselves into a character that breathes, blinks and waves — from the rig-c/core README.
1. **[Parts](/docs/parts/)** merges the painting's two See-through layer sets into rig-space parts, then drafts bones, weighted meshes, physics and a looping idle. 2. **[Pose](/docs/pose/)** cleans a recorded body-18 pose sequence and retargets it onto the rig as an animation. 3. **[Core](/docs/core/)** compiles the rig and motion specs and gates them by named assertions — nothing is written unless every one passes. 4. **[Review](/docs/review/)** lets a person look at what an agent built and hand back feedback bound to a frame, bone or slot. 5. **[Play](/docs/play/)** and the **[adapters](/docs/adapters/)** run the compiled model in a page, PixiJS, Phaser or Three.js, with no Spine runtime. Try it end to end in about three minutes with no GPU: **[Getting started](/docs/getting-started/)**. See what agents do with it on the **[Exam](/exam/)**, and rebuild the published rigs from **[Examples](/examples/)**. ## The toolchain | Package | Latest | Install | What it does | | --- | --- | --- | --- | | [**@rig-c/parts**](/docs/parts/) | `1.40.0` | `npm i -D @rig-c/parts` | Assembles one character painting's decomposed See-through layers into rig-ready parts, then authors weighted meshes, bone chains, physics, and a looping idle over them. | | [**@rig-c/pose**](/docs/pose/) | `0.33.0` | `npm i -D @rig-c/pose` | Cleans and retargets a body-18 pose sequence (from video, dataset, or hand-placed points) onto a rig that rig-c built, gated before keys are written. | | [**rig-c / @rig-c/core**](/docs/core/) | `2.61.0` | `npm i -D rig-c` | The rig compiler: a rig spec and a motion spec in, Spine 4.3 skeleton data (`skeleton.json` + `.atlas`) and `skeleton.model.json` out — gated by named assertions before a byte is written (36 under the default `--profile spine`, all 50 under the opt-in `--profile rig-play`). | | [**@rig-c/review**](/docs/review/) | `0.2.1` | `npm i -D @rig-c/review` | Local human inspection workspace: compare setup geometry, compiled-model playback, source video/sheets, and export frame/bone/slot-bound feedback ready to become an issue. | | [**@rig-c/play**](/docs/play/) | `1.12.0` | `npm i @rig-c/play` | Plays `skeleton.model.json` in the browser with no Spine runtime — as plain DOM elements (`` with CSS `matrix()`) or one `` per player. | | [**@rig-c/adapters**](/docs/adapters/) | `0.1.1` | `npm i @rig-c/pixi`
`npm i @rig-c/phaser`
`npm i @rig-c/three` | Plays a rig-c compiled model inside PixiJS 8, Phaser 4.2+, or Three.js 0.186+ through `@rig-c/play`'s posing core, with no Spine runtime. | ## Built for agents that cannot see An AI agent asked to author a 2D rig cannot see the screen, and standard JSON parsers accept broken rigs in silence — a 4.2-shaped constraint vanishes in 4.3, a mismatched `size:` collapses every UV, a four-number curve array yields `NaN`, and a mesh whose vertex count equals its UV count silently loses its bone weights. rig-c replaces that silence with four structural invariants: 1. **The messages are the UI.** Every refusal names the object, the value found, and the value required. An agent reads one line and knows which field in which file to change — this is rig-c core's own example, a renamed page image: ``` FAIL A17_ATLAS_PAGE_FILES_EXIST: page "../images/hull.png" is not on disk at …/images/hull.png rigc: 1 assertion(s) failed ``` 2. **Nothing is invented.** The compiler never guesses defaults from art or fills in missing numbers. Where the input is silent, it raises a named `CompileError`. 3. **Emit only after green.** `rigc build` compiles, runs its assertion gate, and writes to disk **only** if every assertion passes. No broken file ever outlives the console output that warned about it. 4. **A person can still look.** [`@rig-c/review`](/docs/review/) lets a human inspect the agent's output against reference footage and export structured feedback bound to a frame, bone, or slot. ## Install ```sh # Run the compiler CLI directly with Bun bunx rig-c --help # Install the authoring & compilation toolchain in a project bun add -d @rig-c/parts rig-c @rig-c/pose @rig-c/review # Install the zero-Spine-runtime browser player bun add @rig-c/play ``` ### Install Agent Skills `rig-c` and `@rig-c/parts` ship [Agent Skills](https://agentskills.io) (`skills//SKILL.md`, inside each npm package) that route coding agents directly to the authoritative authoring rules: ```sh # Codex, Gemini CLI, or Antigravity: link rig-c's skills into .agents/skills/ bun add -d rig-c bun rigc skills install # Claude Code: the rig-c/core repository is a plugin marketplace /plugin marketplace add rig-c/core /plugin install rigc@rigc ``` ## Package names and aliases - `rig-c`, `@rig-c/core`, and `spine-rigc` are the same compiler package on npm and install the `rigc` command. - `@rig-c/parts`, `rig-parts`, and `spine-parts` are the same part-assembly package and install the `rig-parts` command. - `@rig-c/play`, `rig-play`, and `spine-html` are the same browser player package. ## Licensing, stated plainly All rig-c packages are **MIT licensed**. The published packages link **no Spine runtime**: - `rigc` emits both Spine 4.3 skeleton data (`skeleton.json` + `skeleton.atlas`) and rig-c's own compiled model document (`skeleton.model.json`). - Playing `skeleton.model.json` with [`@rig-c/play`](/docs/play/) or [`@rig-c/adapters`](/docs/adapters/) integrates no Esoteric Software code and requires no Spine license. - Importing `skeleton.json` into the Spine Editor or playing it with an official Spine Runtime is subject to Esoteric Software's [Spine Editor License Agreement](https://esotericsoftware.com/spine-editor-license) and [Spine Runtimes License Agreement](https://esotericsoftware.com/spine-runtimes-license). ================================================================================ URL: https://rig-c.org/docs/ Markdown: https://rig-c.org/docs/index.md Repository: https://github.com/rig-c ================================================================================ # Docs rig-c is a set of small packages that hand files to each other: a painting split into layers goes in at one end, and a rig that plays in a browser, a game engine, or the Spine editor comes out at the other. These pages explain what each package is for and how it works. Flags, schemas, and every rule live in the package's own repository — each page links there. ## Start here - [**Getting Started**](/docs/getting-started/): 10-step no-GPU walkthrough from pre-decomposed character layers to a compiled rig with idle and wave animations playing in the browser, plus downstream export routes. - [**Parts**](/docs/parts/) — `@rig-c/parts`: @rig-c/parts is a Bun CLI that turns one character painting and its See-through layer decomposition into measured parts, a rig-c rig spec and an idle, gated and packed by rig-c into Spine 4.3 skeleton data. - [**Pose**](/docs/pose/) — `@rig-c/pose`: @rig-c/pose is a Bun CLI that cleans a body-18 joint-position sequence and retargets it onto a rig-c rig as gated, verified bone keys. - [**Core**](/docs/core/) — `rig-c`: rig-c (also @rig-c/core, CLI rigc) compiles a JSON rig spec and motion spec plus loose part PNGs into Spine 4.3 skeleton data, gated by named assertions so nothing invalid is written. - [**Review**](/docs/review/) — `@rig-c/review`: @rig-c/review is a local, loopback-only CLI and browser workspace for a person to inspect a compiled rig, compare it with reference video, and save structured, source-bound feedback for the producing agent. - [**Play**](/docs/play/) — `@rig-c/play`: @rig-c/play is the browser runtime that loads rigc's compiled skeleton.model.json and plays it as plain DOM elements (CSS matrix per rigid slot, small canvases per mesh) or as one canvas per player. - [**Adapters**](/docs/adapters/) — `@rig-c/pixi, @rig-c/phaser, @rig-c/three`: @rig-c/pixi, @rig-c/phaser and @rig-c/three play rigc's skeleton.model.json inside PixiJS, Phaser or Three.js scenes, posed through @rig-c/play and drawn with each host's native objects, without a Spine runtime. ## How the pieces fit 1. **Parts** turns the painting's layers into rig-space parts and authors a first rig over them. 2. **Pose** turns a recorded body pose sequence into an animation on that rig. 3. **Core** (`rigc`) compiles the rig and motion specs, gates them by named assertions, and writes only when every one passes. 4. **Review** lets a person look at what an agent built and hand back feedback bound to a frame, bone, or slot. 5. **Play** and the **adapters** run the compiled model in a page or a game engine with no Spine runtime. ================================================================================ URL: https://rig-c.org/docs/getting-started/ Markdown: https://rig-c.org/docs/getting-started/index.md Repository: https://github.com/rig-c/getting-started ================================================================================ # Getting Started with rig-c You start with one painting of a character. You end with that character rigged — split into movable pieces on a skeleton — breathing, blinking, and waving in your browser. Repository: ## The Whole Pipeline in Three Steps 1. **Paint one character.** Any image model or illustration workflow produces a front-facing, full-body character PNG on a plain white background with arms clear of the body. 2. **Split it into layers, and mark the joints.** [See-through](https://github.com/shitagaki-lab/see-through) cuts the painting into layered parts (twice: full figure + head crop). Body-18 joints come from a lightweight CPU script (`rtmlib`) or hand placement. 3. **Run the rig-c packages on the CPU.** `@rig-c/parts`, `rig-c`, `@rig-c/pose`, and `@rig-c/play` assemble the parts, author meshes and bones, gate the build, retarget motion, and play it in the browser. **No GPU is used in step 3.** ## Try It First — No GPU, About 3 Minutes This walkthrough builds a published example character whose painting and See-through layers are already prepared. Requires [Bun](https://bun.sh) 1.2+ and optionally [uv](https://docs.astral.sh/uv/) for step 6. ### 1. Install the Packages ```sh mkdir rig-c-start && cd rig-c-start git clone https://github.com/rig-c/getting-started mkdir my-rig && cd my-rig bun add @rig-c/parts rig-c @rig-c/pose @rig-c/play ``` ### 2. Fetch the Example Inputs ```sh curl -L -o exam.tar.gz https://codeload.github.com/rig-c/exam/tar.gz/01436ee3f02c189fe1a1e9656fe62068889837f5 tar -xzf exam.tar.gz --strip-components=3 exam-01436ee3f02c189fe1a1e9656fe62068889837f5/tasks/01-build/inputs tar -xzf exam.tar.gz --strip-components=1 exam-01436ee3f02c189fe1a1e9656fe62068889837f5/LICENSE exam-01436ee3f02c189fe1a1e9656fe62068889837f5/NOTICE.md rm exam.tar.gz ``` ### 3. Initialize `config.json` ```sh cat > config.json <<'EOF' { "key": "exam-01", "seethrough": { "resolution": 1024, "steps": 30, "seed": 42, "offload": true }, "assemble": { "rig_scale": 0.5 } } EOF bunx rig-parts inputs --source inputs/painting.png --config config.json --out work ``` ### 4. Propose the Head Box ```sh bunx rig-parts layers inputs/layers/full bunx rig-parts propose --head-box --full inputs/layers/full --canvas 1664x2432 | tail -n 1 > work/head_box.json bun ../getting-started/scripts/take.ts work/head_box.json config.json seethrough.head_box=head_box bunx rig-parts inputs --source inputs/painting.png --config config.json --out work ``` ### 5. Assemble the Parts ```sh bunx rig-parts assemble --propose-plan --source inputs/painting.png --full inputs/layers/full --head inputs/layers/head --config config.json > work/plan.json bun ../getting-started/scripts/take.ts work/plan.json config.json assemble.plan=plan assemble.extend_below_crop=extend_below_crop bunx rig-parts assemble --source inputs/painting.png --full inputs/layers/full --head inputs/layers/head --config config.json --out work ``` ### 6. Detect Body-18 Keypoints ```sh uv run --with rtmlib --with onnxruntime python ../getting-started/scripts/keypoints.py inputs/painting.png --out keypoints.json ``` ### 7. Draft Bones, Meshes, Regions, and Idle Motion ```sh bunx rig-parts propose --parts work/rig --source inputs/painting.png --out work --keypoints keypoints.json bun ../getting-started/scripts/take.ts work/proposal.json config.json bones meshes regions motion ``` ### 8. Build and Gate the Rig ```sh bunx rig-parts build --config config.json --source inputs/painting.png --full inputs/layers/full --head inputs/layers/head --out out --loop ``` Expected verdict: `[check] check: PASS; 10 of 10 bar(s) measured`, followed by `build: PASS` and `out/idle.gif`. ### 9. Retarget a 3-Second Wave with `@rig-c/pose` ```sh bun ../getting-started/scripts/wave.ts keypoints.json wave.pose.json cat > map.json <<'EOF' { "spec": "rig-pose-map/1", "chains": [ { "name": "trunk", "bones": ["chest"], "joints": ["mid_hip", "neck"], "aim": ["neck"] }, { "name": "arm_r", "bones": ["sleeve_r0", "sleeve_r1"], "joints": ["r_shoulder", "r_elbow", "r_wrist"], "bend": "free" }, { "name": "arm_l", "bones": ["sleeve_l0", "sleeve_l1"], "joints": ["l_shoulder", "l_elbow", "l_wrist"], "bend": "free" } ], "translate": { "bone": "hip", "joint": "mid_hip", "scale": { "pose": ["mid_hip", "neck"], "rig": ["hip", "neck"] } } } EOF bunx rig-pose retarget --rig out/rig --map map.json --pose wave.pose.json --out wave.motion.json --name wave --profile spine-html --build wave-build ``` ### 10. Play It in the Browser ```sh bun ../getting-started/scripts/serve.ts # Open http://localhost:3000/?model=wave-build/skeleton.model.json&anim=wave ``` ## Three Ways to Use the Output 1. **On the web with [`@rig-c/play`](/docs/play/) or [`@rig-c/adapters`](/docs/adapters/)**: Load `skeleton.model.json` and part PNGs directly. MIT licensed, zero Spine runtime dependencies. 2. **In the Spine 4.3 Editor**: Import `out/check/build/skeleton.json` via `Import Data` and point `Images` to `out/rig/images/` to refine timelines by hand (requires rig-c 2.51.1+ and a Spine Editor license). 3. **In a game engine via official Spine Runtimes**: Load `skeleton.json` and `skeleton.atlas` in Unity, Godot, Unreal, or C++ runtimes under the Spine Runtimes License. ================================================================================ URL: https://rig-c.org/docs/parts/ Markdown: https://rig-c.org/docs/parts/index.md Package: @rig-c/parts@1.40.0 Repository: https://github.com/rig-c/parts ================================================================================ # @rig-c/parts Turn one anime character painting into a rigged, idling 2D character. Every stage is checked before anything is written. ## What it is `@rig-c/parts` (command `rig-parts`) is a command-line tool. It takes a single character painting and the layers See-through decomposed it into. It merges them into measured parts, authors weighted meshes, bone chains and a looping idle, and hands that spec to rig-c to compile, gate, pack, render and check. ## When to use it Use it when you start from a painting, not from a finished rig. It is built for agents that cannot see the image: every stage prints named, numeric findings instead of asking you to look. It also reads an artist's own layered PSD, one layer per part, with no See-through step. Do not use it to write Spine data directly. rig-parts never does that itself. Compiling, gating and packing belong to [rig-c](/docs/core/). Drawing the result on a web page belongs to [rig-play](/docs/play/). To set up the machine that makes the painting and the layers, start at [Getting started](/docs/getting-started/). ## What it solves Cutting a painted character into rig parts is slow, and the mistakes show up late: a layer holds the wrong pixels, a part leaves a hole, a chain swings a skirt about its middle. rig-parts measures these. A refusal names the object, the value found and the value required. Nothing is written after a red, and no value is invented where the input is silent. ## What you get A green `build` ends like a Spine editor export, with one packed atlas page: - **The artifact**: `skeleton.json`, `skeleton.atlas` and `skeleton.png` under `check/build/`. This is Spine 4.3 skeleton data, written by rig-c and gated under the `rig-play` profile. - **The intermediates**: the loose `parts/`, `parts.json` (where every part came from), the recomposite and its error map. - **The rig spec**: `rig.json` and `motion.json` in rig-c's spec. - **The checks**: both gate files, the idle's frames and `check.json`. - **With `--loop`**: the idle as a lossless APNG, an indexed APNG and a GIF. ## How it works 1. **Inputs.** `inputs` cuts the two images See-through is fed: the painting on a white square, and a square crop around the head. The head run exists because a full-figure run leaves the eyes too small to separate. 2. **Layers.** You run See-through by any route: a hosted demo, the upstream CLI, or ComfyUI. rig-parts reads its `.psd` or the ComfyUI wrapper form. An optional `comfy` adapter drives a ComfyUI box; nothing else needs one. 3. **Assemble.** The two runs merge into rig-space parts. Uncovered holes are listed, and the error map shows them in red. 4. **Propose.** `propose` drafts bones, meshes, regions and an idle, with an overlay to correct against. It is a draft, not a step of `build`. You copy its sections into `config.json`, and LINT lines flag what still looks wrong. 5. **Build.** `build` runs assemble, rig and check in one process and stops at the first refusal. ## Key concepts - **See-through layers**: the decomposition of the painting into tagged layers, one run on the full figure and one on the head. - **Parts**: the merged, measured pieces in rig space, recorded in `parts.json`. - **Proposal**: the drafted bones, meshes, regions and motion in `proposal.json`, to be corrected. - **Config**: `config.json`, the character's part plan, head box, bones and idle. Unknown or missing fields are refused by name. - **FAIL line**: a refusal; it names a rule and ends with `(see rig-parts guide )`. - **Gate**: rig-c's validation of the compiled rig, here under the `rig-play` profile. ## Install Requires [Bun](https://bun.sh) 1.2 or later. rig-c comes with it as a dependency. ```sh npm i -D @rig-c/parts rig-parts --help ``` Output is Spine skeleton data, so using it in a product requires a Spine Editor licence. ## Go deeper - [README: What it takes in](https://github.com/rig-c/parts#what-it-takes-in) and [What it gives out](https://github.com/rig-c/parts#what-it-gives-out) - [README: The loop, for an agent](https://github.com/rig-c/parts#the-loop-for-an-agent), the full command sequence - [docs/AUTHORING.md](https://github.com/rig-c/parts/blob/main/docs/AUTHORING.md): every config field, what to read after each stage, every refusal - [docs/PAINTING.md](https://github.com/rig-c/parts/blob/main/docs/PAINTING.md): what makes a painting riggable - [docs/STABILITY.md](https://github.com/rig-c/parts/blob/main/docs/STABILITY.md): what 1.0.0 holds stable - [NOTICE.md](https://github.com/rig-c/parts/blob/main/NOTICE.md): third-party terms, See-through's included - [CHANGELOG.md](https://github.com/rig-c/parts/blob/main/CHANGELOG.md) - [npm: @rig-c/parts](https://www.npmjs.com/package/@rig-c/parts) ================================================================================ URL: https://rig-c.org/docs/pose/ Markdown: https://rig-c.org/docs/pose/index.md Package: @rig-c/pose@0.33.0 Repository: https://github.com/rig-c/pose ================================================================================ # @rig-c/pose Pose moves a rig. It takes joint positions over time and writes them onto a rig-c rig as bone keys, and it checks those keys before it writes anything. ## What it is A command-line tool, `rig-pose`, that turns a body-18 pose sequence into an animation in rig-c's motion format. In the rig-c toolchain, [core](/docs/core/) gates the rig, [parts](/docs/parts/) builds it, [play](/docs/play/) plays it, and pose moves it. Version 0.x is a prototype: the format, the commands and the output can change in any release before 1.0. ## When to use it Use it when you already have joint positions (from a pose model, a dataset, or placed by hand) and a rig-c rig with limb chains, and you want an animation that follows them. Do not use it to: - **Get the poses.** It does not extract poses from video; how you get joint positions is up to you. - **Build the rig.** The rig must have chains: a thigh with a shin below it, an upper arm with a forearm below it. [@rig-c/parts](/docs/parts/) builds such a rig from a painting. A rig whose arm is one bone is refused. - **Animate hands, fingers or depth.** It works in 2D. A limb pointing at the camera foreshortens, and the rig matches its direction, not its length. ## What it solves A pose model reads each frame alone, so joints shake from frame to frame, and every key would carry that shake. Mapping picture angles onto bones also has traps: setup rotations, and parents that turn their children. Pose cleans the sequence once, where it can be inspected, and then refuses to write keys that do not land where the pose asked. ## What you get - A cleaned `rig-pose-sequence/1` file that carries a `cleaned` record of what was done. - A motion file with the new animation, for the rig's motion spec. - With `--report`, a `rig-pose-report/1` JSON file of everything the run found. - With `--build`, the gated build, which `rigc preview` can play. - From `compare`, a `rig-pose-compare/1` report and an optional PNG sheet. ## How it works 1. **Clean.** `rig-pose clean` removes spikes, fills low-score or occluded joints from their neighbours, smooths each joint, and holds joints that have stopped. `retarget` reads only a sequence that `clean` wrote. COCO-17 input is converted here with `--coco`. 2. **Map.** You write a map that says which bones carry which joints, chain by chain. 3. **Retarget.** For every frame and every mapped bone, the bone is turned so it points the way its segment points in the picture, minus its setup angle and its parent's turn. 4. **Check.** rig-c's gate must be green with the rig as it is and with the animation in. Every mapped bone must land on its asked angle on every frame, posed by rig-c's own poser. Hinges must bend only one way. If any check fails, nothing is written and every reason is printed. 5. **List what it cannot decide.** Lines such as `HOLD`, `END-ON` and `IDLE-DROPPED` name what you should look at. ```sh bun add @rig-c/pose rig-pose retarget --rig out/rig --map map.json --sequence dance.pose.json --out motion.json --animation dance ``` ## Key concepts - **body-18**: the 18 joints the sequence uses (`nose`, `neck`, shoulders, elbows, wrists, hips, knees, ankles, eyes, ears); `r`/`l` are the subject's sides. - **chain**: a limb in the map, as bones that descend from one another; bone *k* carries the segment from joint *k* to joint *k*+1. - **lands**: a mapped bone, posed by rig-c's poser, is within 0.01° of the angle the pose asks for. - **cleaned record**: the `cleaned` block `clean` writes into the sequence; `retarget` requires it. - **alternates**: sets of slots switched together to show a second drawing for a pose bone rotation cannot carry. ## Go deeper - [Try it](https://github.com/rig-c/pose#try-it) and the [wave example](https://github.com/rig-c/pose/tree/main/examples/wave), with no art and no video - [Clean first](https://github.com/rig-c/pose#clean-first-rig-pose-clean) - [What it does](https://github.com/rig-c/pose#what-it-does): every check and every listed line - [The pose format](https://github.com/rig-c/pose#the-pose-rig-pose-sequence1) and [the map format](https://github.com/rig-c/pose#the-map-rig-pose-map1) - [Alternate drawings](https://github.com/rig-c/pose#alternate-drawings-alternates) - [Compare](https://github.com/rig-c/pose#compare-the-rigs-render-against-the-video) - [What it does not do](https://github.com/rig-c/pose#what-it-does-not-do) and [Requirements](https://github.com/rig-c/pose#requirements) - [CHANGELOG](https://github.com/rig-c/pose/blob/main/CHANGELOG.md) and the [npm page](https://www.npmjs.com/package/@rig-c/pose) - `rig-pose --help` lists every flag. ================================================================================ URL: https://rig-c.org/docs/core/ Markdown: https://rig-c.org/docs/core/index.md Package: rig-c@2.61.0 Repository: https://github.com/rig-c/core ================================================================================ # rig-c core: the rig compiler rigc turns loose part PNGs and two small JSON files into Spine 4.3 skeleton data. It checks the result against a list of named assertions first, and writes nothing if any of them fails. ## What it is rigc is a rig compiler: a rig spec and a motion spec in, skeleton data out. It was built so AI agents can author rigs and check their own work, and it ships as an agent skill. On npm it is `rig-c`; `@rig-c/core` is the same package under the toolchain's scope, and the command it installs is `rigc`. ## When to use it Use it when you want Spine skeleton data generated from a spec and checked before it is written. The output loads in any Spine runtime and imports into the Spine editor, so the intended hand-off is: an AI drafts, a human refines in the editor. Reach for a neighbour instead when: - you start from one painting rather than finished part PNGs: [@rig-c/parts](/docs/parts/) produces the parts and rig specs, verified through rig-c; - you have a body-18 pose sequence to put on a rig: [@rig-c/pose](/docs/pose/) writes the bone keys in rigc's motion format; - you want to play the result in a browser without a Spine runtime: [@rig-c/play](/docs/play/) plays the `skeleton.model.json` that `rigc build` writes; - a person needs to look at a build and leave feedback: [@rig-c/review](/docs/review/). ## What it solves An agent authoring a rig cannot tell whether it succeeded, because Spine's JSON parser accepts a lot of nonsense silently. A constraint in the 4.2 shape simply vanishes. A `size:` that disagrees with the PNG collapses every UV. A four-number curve array yields NaN. Each of these loads clean, plays, and is wrong. rigc makes the failure legible: every failure is named by rule, and nothing reaches disk. ## What you get - `skeleton.json` and `skeleton.atlas` in the Spine 4.3 format. - `skeleton.model.json`, rigc's own compiled model, written beside them. - A gate report, which names the profile it ran; `--report` also writes it as JSON. - On failure: one line per failed rule, ending with `(see rigc guide )`, and no files. ## How it works 1. **Measure the art.** rigc reads the PNGs themselves instead of trusting sizes you typed, so the skeleton and the atlas cannot drift apart. 2. **Compile two specs.** The rig spec (`rigc-rig/1`) holds structure: bones, slots in draw order, skins. The motion spec (`rigc-motion/1`) holds time: animations, tracks, keys. 3. **Gate.** The compiled rig is checked against named assertions. The default profile, `spine`, runs the 36 validity rules: is this valid Spine 4.3 that any runtime plays correctly? `--profile rig-play` runs all 50; the extra 14 are one renderer's and one canvas budget's policy, which is why they are opt-in. 4. **Write, or refuse.** Only a green gate writes `--out`. 5. **Look at it.** A green gate says nothing about the picture, so `render`, `inspect` and `check` show and compare what was built. The published package links no Spine runtime. Install `@esotericsoftware/spine-core` beside it and the same `rigc` also runs the round trip through Spine's own parser, plus the commands that need it: `validate`, `preview`, `vote`, `bench` and `bonedist`. The Spine Runtimes License Agreement applies to that dependency wherever it is installed. rigc runs on Bun 1.2.0 or later. ```bash bun add -d rig-c bun rigc build --rig rig.json --motion motion.json --out build/ bun rigc render --candidate build/ ``` ## Key concepts - **Rig spec** — the structure file: bones, the slots array (the setup draw order) and skins. - **Motion spec** — the time file, aimed at the rig by name. - **Named assertions** — the rules the gate runs; each failure names its rule. - **Profile** — which rulebook the gate checks against: `spine` (default) or `rig-play`. - **`A00_ROUNDTRIP_PARSE`** — Spine's own parse; it runs only where spine-core is installed and reports SKIP elsewhere. - **`ingest`** — `build` run backwards: a Spine 4.3 `skeleton.json` in, the two specs that rebuild it byte for byte out. ## Go deeper - [README: What you get](https://github.com/rig-c/core#what-you-get) · [Install](https://github.com/rig-c/core#install) · [Install it into your agent](https://github.com/rig-c/core#install-it-into-your-agent) - [README: First rig in ten minutes](https://github.com/rig-c/core#first-rig-in-ten-minutes) - [README: Commands](https://github.com/rig-c/core#commands) and [Starting from a skeleton you already have](https://github.com/rig-c/core#starting-from-a-skeleton-you-already-have) - [README: Licensing, stated plainly](https://github.com/rig-c/core#licensing-stated-plainly) and [NOTICE.md](https://github.com/rig-c/core/blob/main/NOTICE.md) - [docs/AUTHORING.md](https://github.com/rig-c/core/blob/main/docs/AUTHORING.md) — the format guide; read it before writing a spec - [docs/RIGGING.md](https://github.com/rig-c/core/blob/main/docs/RIGGING.md) · [docs/MOTION.md](https://github.com/rig-c/core/blob/main/docs/MOTION.md) · [docs/FACE.md](https://github.com/rig-c/core/blob/main/docs/FACE.md) · [docs/INGEST.md](https://github.com/rig-c/core/blob/main/docs/INGEST.md) · [docs/PROMPTING.md](https://github.com/rig-c/core/blob/main/docs/PROMPTING.md) - [docs/BENCHMARK.md](https://github.com/rig-c/core/blob/main/docs/BENCHMARK.md) — why you can trust the output, and the 50 assertions with their profiles - [npm: rig-c](https://www.npmjs.com/package/rig-c) · [CHANGELOG.md](https://github.com/rig-c/core/blob/main/CHANGELOG.md) - Start here: [/docs/getting-started/](/docs/getting-started/) ================================================================================ URL: https://rig-c.org/docs/review/ Markdown: https://rig-c.org/docs/review/index.md Package: @rig-c/review@0.2.1 Repository: https://github.com/rig-c/review ================================================================================ # Review Review is the human inspection gate in the rig-c toolchain. A person opens an agent's rig output in one local workspace, checks it, and saves feedback that the agent can read back. ## What it is `@rig-c/review` is a CLI, `rig-review`, that serves a browser workspace on `127.0.0.1`. It plays a compiled model through `@rig-c/play`, shows local image, video and pose-sequence references beside it, and records the person's review decision and feedback. ## When to use it Use it after a [Core](/docs/core/) build, when a person needs to look at the result before it goes on. The agent does not have to build a new viewer for each rig. Do not use it to fix the rig. Motion is view, annotate and export only: it never retimes, authors keys or writes `motion.json`. It does not edit meshes, weights or source art. It also does not replace Core's compiler gate; `check` validates the delivery contract and model envelope, not visual quality. To ship a rig into a game, use [Play](/docs/play/) or an [engine adapter](/docs/adapters/). ## What it solves An agent can produce a rig, but a person has to judge it. Without a shared tool, that judgment ends up as loose notes that point at nothing exact. Review ties each piece of feedback to the exact bytes that were reviewed, and to a frame interval and a bone or slot target. The agent then retrieves it with one command. If the input changes, the old approval does not carry over. ## What you get - A **review status**: `approved`, `changes-requested` or `pending`. Opening never approves. - **Feedback** items with an inclusive frame interval, a bone/slot/rig target, a defect/quality category and a one-line summary. - A `reviewedSource` record: package revision, viewer/runtime versions, and SHA-256 plus path for the reviewed rig and motion. - JSON and issue-ready Markdown exports (`--format issue`). - **Frame strip** exports as PNG or JSON, with a `.png.json` provenance sidecar. ## How it works 1. Install it beside the agent and run `open` on the output folder. It recognizes `skeleton.model.json` at the root or under `build/`, plus `motion.json`, `report.json`, source videos and pose sequences. It reads them without changing them. 2. `open` hashes the folder, starts or reuses a background loopback instance, prints its URL and exits. It never opens a browser and binds only `127.0.0.1`. 3. The person inspects playback, parts and references, then explicitly saves a status and feedback. Feedback is stored under `~/.local/state/rig-c-review/`, outside the delivered files. 4. The agent runs `feedback` on the same folder to read the session JSON. Changed content starts a fresh pending session. 5. Optionally, `compare` seeks two outputs against one reference video with a single playhead. ```sh npm i -D @rig-c/review npx rig-review open /absolute/path/to/output ``` It runs under Bun 1.3.0 or later. The CLI is the supported surface; no importable API is promised. ## Key concepts - **Output folder**: an existing agent output opened as-is, with no manifest required. - **`review.json`**: an optional curated manifest with named checkpoints, references and angle axes. - **Checkpoint**: a named inspection point in a curated package, with its own outcome and notes. - **Producer clock**: `fps` plus `frame0`, or exact `frameTimes[]`, declared in the report. Without it the UI shows `rate unknown`. - **Reference binding**: the name and byte hash of a selected external video, bound into sessions and exports. - **Write capability**: a per-instance secret carried in the URL's `#cap=` fragment. A link without it opens read-only. ## Go deeper - [README: Start](https://github.com/rig-c/review#start) - [README: Feedback ownership](https://github.com/rig-c/review#feedback-ownership) - [README: Compare two outputs](https://github.com/rig-c/review#compare-two-outputs) - [README: Frame strip export](https://github.com/rig-c/review#frame-strip-export) - [README: Managed front and write capability](https://github.com/rig-c/review#managed-front-and-write-capability) - [README: Control the current inspection page](https://github.com/rig-c/review#control-the-current-inspection-page) - [docs/REVIEW_PACKAGE.md](https://github.com/rig-c/review/blob/main/docs/REVIEW_PACKAGE.md) (package format and HTTP contract) - [docs/DESIGN.md](https://github.com/rig-c/review/blob/main/docs/DESIGN.md) (product boundary and direction) - [CHANGELOG](https://github.com/rig-c/review/blob/main/CHANGELOG.md) - [npm: @rig-c/review](https://www.npmjs.com/package/@rig-c/review) ================================================================================ URL: https://rig-c.org/docs/play/ Markdown: https://rig-c.org/docs/play/index.md Package: @rig-c/play@1.12.0 Repository: https://github.com/rig-c/play ================================================================================ # Play Play is the runtime of the rig-c toolchain. It loads the model a [Core](/docs/core/) build writes and animates it in a web page. ## What it is `@rig-c/play` plays `skeleton.model.json`, the compiled model document that `rigc build` writes. In the default `dom` mode, each rigid slot is one absolutely positioned ``, posed with one CSS `matrix()` write per frame, and deforming meshes draw on small per-part canvases. In `canvas` mode the whole frame draws into one `` per player. ## When to use it Use it to show a rigc-built character in a browser page, with no game engine. It suits a few characters that mostly hold a pose with some parts deforming. The README reports that this case holds 60 fps on every engine it measured. When you already render with PixiJS, Phaser or Three.js, use the [engine adapters](/docs/adapters/) instead. They draw Play's posed frames inside that engine. To inspect a rig and leave feedback, use [Review](/docs/review/). Play does not play Spine exports; a Spine export is refused by name. ## What it solves A rigged character usually means a canvas runtime that rasterizes everything. For a rigid part, though, the bone transform is a plain affine map that CSS `matrix()` expresses exactly. So the rigid parts can live in the DOM, where the browser composites them and you can inspect and style them like any element. Play keeps that path and adds what the DOM cannot do alone: per-part mesh canvases, `clip-path` clipping, and dirty-skip for meshes that did not move. ## What you get - `loadModel()`: loads the model document and cuts each atlas region into its own bitmap. The `.atlas` and `skeleton.json` next to it are not fetched. - `RigPlayer`: plays, queues and mixes animations on several tracks, and steps one `frame(delta)` at a time. - `DomRenderer` and `CanvasRenderer`: the two render modes. You can switch in place with `player.mode`. - `PosedFrame`: a plain record of what to draw this frame. Any code that produces one can draw through the renderer. - Read-only queries: `bone()`, `bounds()`, `posedFrame()` and `slotIdentity()`. - Attachment sets from an optional `sets.json`, switched with `setSet()`. ## How it works 1. `loadModel` reads the compiled model document with `rig-c/core`, which is bundled into the package. There is nothing else to install. 2. At load time each region on the document's pages is cut into its own bitmap, with its rotation restored. 3. `RigPlayer` opens an animation on a live track. The core poses bones, constraints, physics, deform and draw order on the CPU, one `dt` at a time. 4. Each frame the pose becomes a `PosedFrame`: region corners or mesh vertices, UVs, tint, blend and clip, in draw order. 5. For a region, the renderer derives the affine from three corners and writes one `matrix()` string. Meshes draw through one shared WebGL context by default, and fall back to canvas2d. ```sh npm i @rig-c/play ``` ## Key concepts - **Model document**: `skeleton.model.json` (spec `rigc-compiled/3`). It holds the skeleton, animations and region placement. - **Region attachment**: a rigid part, drawn as an `` with a CSS matrix. - **Mesh attachment**: a deforming part, drawn on its own small canvas sized to its world bounds. - **Render mode**: `dom` (the default) or `canvas`. - **Mesh backend**: `webgl` (the default since 1.9) or `canvas2d`. - **Dirty-skip**: a mesh whose vertices match its last raster reuses that raster. - **Attachment set**: a named swap of slot attachments, declared in `sets.json`. ## Go deeper - [README: Install](https://github.com/rig-c/play#install) - [README: A minimal page](https://github.com/rig-c/play#a-minimal-page) - [README: Drawing your own frames](https://github.com/rig-c/play#drawing-your-own-frames) - [README: Runtime knobs and what they cost](https://github.com/rig-c/play#runtime-knobs-and-what-they-cost) - [README: Benchmark](https://github.com/rig-c/play#benchmark-dom-canvas-and-official-webgl) - [README: How it works](https://github.com/rig-c/play#how-it-works) - [README: License](https://github.com/rig-c/play#license) and [NOTICE.md](https://github.com/rig-c/play/blob/main/NOTICE.md) - [CHANGELOG](https://github.com/rig-c/play/blob/main/CHANGELOG.md) - [npm: @rig-c/play](https://www.npmjs.com/package/@rig-c/play) ================================================================================ URL: https://rig-c.org/docs/adapters/ Markdown: https://rig-c.org/docs/adapters/index.md Package: @rig-c/pixi, @rig-c/phaser, @rig-c/three@0.1.1, 0.1.1, 0.1.1 Repository: https://github.com/rig-c/adapters ================================================================================ # Engine adapters The adapters put a rigc-built rig inside the engine or renderer your game already uses. [Play](/docs/play/) computes the pose; the host draws it with its own objects. ## What it is Three packages, each versioned on its own, all at 0.1.1 with 0.x APIs: - `@rig-c/pixi`: a PixiJS 8 adapter. - `@rig-c/phaser`: a Phaser 4.2+ adapter for WebGL scenes. - `@rig-c/three`: a native Three.js 0.186.1 renderer and live `Group`. Each one reads the model document `rigc build` writes, `skeleton.model.json`, through `@rig-c/play`. ## When to use it Use an adapter when your game or page already renders with PixiJS, Phaser or Three.js, and the rig must sit in that scene graph with your other objects. Three.js is a 3D renderer, so its adapter is for 2D characters inside 3D scenes and interactive pages. If you only need a rig in a web page, with no engine, use [Play](/docs/play/) directly. It draws as DOM elements or one canvas. Native engines such as Godot or Unity are planned, not available. ## What it solves rigc compiles a rig into two things side by side: Spine 4.3 skeleton data and its own model document. An official Spine runtime can load the Spine data, but it brings the Spine Runtimes licence with it. An adapter is a third way: rig-c's own poser runs inside the engine's scene graph and renderer, reads the model document, and links no Spine runtime. ## What you get - **A live object** per host: `PixiRig` (a Pixi `Container`), `PhaserRig` (a Phaser `Container`) and `ThreeRig` (a flat Three.js `Group`). Each owns an independent player and exposes `play`, `seek`, `bone()` and `bounds()`. - **A renderer** per host for when you own the player: `PixiRenderer`, `PhaserRenderer` and `ThreeRenderer`. Each draws a supplied `PosedFrame`. - **Shared page textures**: several rigs over one `ModelAssets` load share page textures until the last holder releases them. ## How it works 1. Load the model with `@rig-c/play`'s `loadModel`, using the files `rigc build` wrote, unmodified. 2. Create the host object, for example `new PixiRig(assets, { ticker: app.ticker })`, and add it to your stage or scene. 3. Each update, `@rig-c/play` poses the rig and produces a `PosedFrame` record. 4. The adapter reads slot corners or mesh vertices, page UVs, tint, blend and clip straight from that record. It maps world `(x, y)` to `(x, -y)` and draws with the host's native objects. 5. On removal, `destroy()` frees that rig's own resources. Dispose the shared assets after the last rig is gone. ```sh npm install @rig-c/pixi pixi.js @rig-c/play ``` Swap in `@rig-c/phaser phaser` or `@rig-c/three three` for the other hosts. ## Key concepts - **Host**: the engine or renderer an adapter targets. Each host lives in `packages/`. - **Model document**: `skeleton.model.json`, the source the adapters read. Spine is one export of it. - **`PosedFrame`**: the per-frame record `@rig-c/play` produces and every renderer draws. - **`ModelAssets`**: one `loadModel` result, which several rigs can share. - **Parity**: an adapter plays the same pose for the same time as `@rig-c/play`, held to the player's output by a test. ## Go deeper - [README: Why this exists](https://github.com/rig-c/adapters#why-this-exists) - [README: What an adapter promises](https://github.com/rig-c/adapters#what-an-adapter-promises) - [packages/pixi README](https://github.com/rig-c/adapters/tree/main/packages/pixi#readme) - [packages/phaser README](https://github.com/rig-c/adapters/tree/main/packages/phaser#readme) (renderer contract) - [packages/three README](https://github.com/rig-c/adapters/tree/main/packages/three#readme) (native drawing and scene placement) - [docs/ADDING_A_HOST.md](https://github.com/rig-c/adapters/blob/main/docs/ADDING_A_HOST.md) - Changelogs: [pixi](https://github.com/rig-c/adapters/blob/main/packages/pixi/CHANGELOG.md), [phaser](https://github.com/rig-c/adapters/blob/main/packages/phaser/CHANGELOG.md), [three](https://github.com/rig-c/adapters/blob/main/packages/three/CHANGELOG.md) - npm: [@rig-c/pixi](https://www.npmjs.com/package/@rig-c/pixi), [@rig-c/phaser](https://www.npmjs.com/package/@rig-c/phaser), [@rig-c/three](https://www.npmjs.com/package/@rig-c/three) ================================================================================ URL: https://rig-c.org/examples/ Markdown: https://rig-c.org/examples/index.md Repository: https://github.com/rig-c/parts-examples ================================================================================ # Reproducible Examples (`parts-examples` & `trailer`) Every public rig-c showcase ships with its generated source paintings, See-through layer decompositions, agent-authored configs, and one-command deterministic rebuild scripts. ## 1. `rig-c/parts-examples` — Public Character Inputs & The 20-Rig Agent Family Repository: ### Single-Character Fixtures | Key | Seed | Checkpoint | See-through Layers | Purpose | | --- | --- | --- | --- | --- | | `demo` | `71006` (+ hand detailer) | Hassaku XL (Illustrious) v1.3 Style A | 29 full + 29 head | The primary `@rig-c/parts` README character: twin tails, bow, layered skirt, arms held clear of the body. | | `scarf` | `72004` | Pony Diffusion V6 XL | 29 full + 29 head | A very long red scarf with both ends hanging free, knit sweater and pleated skirt: the hanging element the others lack. | | `three-quarter` | `250011` | Hassaku XL (Illustrious) v1.3 Style A | 29 full + 29 head | Head turned toward image left and tilted for head-frame turn measurements. | | `wind` | `372108` | Hassaku XL (Illustrious) v1.3 Style A | 29 full + 29 head | Very long ribbon-wrapped twin tails and a wide two-layer skirt, painted for wind interaction. | | `reference-sample` | `70011` | Pony Diffusion V6 XL | 29 full + 29 head | Regression fixture held to the reference implementation's outputs. | | `reference-demo` | `71004` | Pony Diffusion V6 XL | 29 full + 29 head | Regression fixture held to the reference implementation's outputs. | ### `family/` — 5 Characters × 4 Outfits (20 Rigs, 396 Parts) Starting from one wide group illustration (`1024×571` RGBA) upscaled with `4x-AnimeSharp` to `4096×2284`, the `family/` suite overcomes See-through's fixed `1024×1024` resolution limit by combining 2-pass (`full` + `head`) decomposition, visible-surface 4x detail injection, and hash-bound declarative mesh/binding repair recipes (`declared-repairs.json`) across 5 characters and 4 outfit sets (`office`, `homewear`, `swimwear`, `uniform`). ```sh # Deterministic rebuild & compiler gate across all 20 rigs (396 parts) bun install --cwd family/tools/outline-field-islands --frozen-lockfile node family/tools/verify-reproducibility.mjs --out /tmp/new-repro-evidence bun family/tools/verify-accepted.mjs --out /tmp/new-family-evidence ``` ## 2. `rig-c/trailer` — 12-Second Reproducible Animated Short Repository: A character sitting on a swing under a night sky breathes, tilts her head, smiles, kicks her legs, hops, and waves, her twin tails following on physics chains — rebuilt byte-for-byte (240 frames at 20 fps, `960×540` WebP + `1920×1080` PNG frames) from one painting, two See-through layer sets, and agent-authored configs: ```sh git clone https://github.com/rig-c/trailer && cd trailer pip install -r requirements.txt ./build.sh ``` ================================================================================ URL: https://rig-c.org/exam/ Markdown: https://rig-c.org/exam/index.md Repository: https://github.com/rig-c/exam ================================================================================ # rig-c/exam — Does Your AI Model Pass? **An open-book exam for AI agents: build a rig from one painting with the published rig-c tools, and write down what you expected before each step.** - **Repository**: - **Prompt (Basic)**: - **Advanced Edition**: - **License**: CC BY-NC 4.0 The rig-c tools are written for agents that cannot see what they build. `rig-c/exam` measures whether that holds for a fresh agent session that has never seen the tools before: the only help is what ships inside the installed packages (`README.md`, `docs/`, `--help`). Before every command that changes a file, the examinee must record what it read and what it expects in `JOURNAL.md`. Where expectation and reality differ — where the agent says *WTF?* — a tool message or guide was missing something. ## Basic Exam Leaderboard (Tasks 01-build, 02-move, 03-correct) 5 independent sittings graded from submitted input files via `python3 grade.py`: | Model | Sittings | 01-build | 02-move | 03-correct | Total Lines Passed | Minutes | Tokens (Fresh In + Out) | | --- | :-: | :-: | :-: | :-: | :-: | :-: | :-: | | **Claude Haiku** (`2026-10-12-haiku`) | 1 | 4 / 4 | 7 / 7 | 5 / 5 | **16 / 16** | 21.0 | 531k | | **Gemini 3.8 Flash** (`2026-10-13-gemini-3.8-flash`) | 1 | 4 / 4 | 7 / 7 | 5 / 5 | **16 / 16** | 20.0 | 1.4M | | **`gpt-6-sol`** (`2026-10-13-gpt-6-sol`) | 1 | 4 / 4 | 7 / 7 | 5 / 5 | **16 / 16** | 14.1 | 258k | | **Sol 6.1 (`gpt-6.1-sol`)** (2 sittings) | 2 | 4 / 4 | 7 / 7 | 5 / 5 | **32 / 32** (16/16 each) | 14.2 – 15.3 | 195k – 270k | ## Advanced Exam Leaderboard (Walk · Run · Dance Pose Retargeting) Starts from a built rig: the agent retargets recorded walk (R1), run (R2), and dance (R3) pose sequences with [`@rig-c/pose`](/docs/pose/), one round per fresh session, fixing what the diagnostic numbers report without ever seeing the footage: | Model | R1 Walk | R2 Run | R3 Dance | 0.21 Shin-Scale Row (What-If) | Minutes (R1 · R2 · R3) | | --- | :-: | :-: | :-: | --- | --- | | `claude-haiku-5-5` | **9 / 9** | 8 / 14 (FAIL) | **13 / 13** | passes all 3 | `3.1 · 2.4 · 7.4` | | `claude-opus-5-5` | **9 / 9** | **14 / 14** | **13 / 13** | fails R2 (`0.106`) | `8.2 · 8.7 · 8.4` | | `claude-sonnet-5-5` | **9 / 9** | **14 / 14** | **13 / 13** | passes all 3 | `7.3 · 10.3 · 18.7` | | `gemini-3.8-flash-medium` | **9 / 9** | **14 / 14** | **13 / 13** | fails R2 (`0.106`) | `8.1 · 14.3 · 11.4` | | `gemini-4-argon-high` | **9 / 9** | **14 / 14** | **13 / 13** | passes all 3 | `16.8 · 20.3 · 32.5` | ## Rules of the Exam 1. **Open book, closed neighbours.** Examinees may read anything inside the pinned npm packages and public tool repos, but may not read another examinee's run under `results/` or ask a human. 2. **Pinned versions.** `npm ci` installs the exact round versions declared in `package.json`. 3. **Journal before you act.** Every step in `JOURNAL.md` must record expectations before running the command. 4. **Submit the transcript.** Raw session logs are submitted alongside `JOURNAL.md`. 5. **The grader rebuilds from inputs.** `grade.py` trusts only the handed-in config/spec files and rebuilds from scratch.