DEV Community

Cover image for I built ChibiRigKit: turning a single character image into an animated 2D rig
milkc0de
milkc0de

Posted on

I built ChibiRigKit: turning a single character image into an animated 2D rig

#javascript #python #ai #opensource

🎮 Try the interactive demo first:
https://milkc0de.github.io/ChibiRigKit/

You can play with the motion system, try the 9-direction head pose challenge, explore the AI-to-browser pipeline, and launch the actual generated ChibiRigKit browser rig.

In this post, I'll explain how I built ChibiRigKit and why I designed AI as part of the creation pipeline, rather than making it a runtime dependency.

I built ChibiRigKit, an open-source tool that turns a single character illustration into an animated 2D character.

It can add things like:

  • blinking
  • eye movement
  • random face movement
  • head rotation
  • hair and clothing motion
  • background replacement
  • WebM recording

The project is available on GitHub under the MIT License:

https://github.com/milkc0de/ChibiRigKit

ChibiRigKit demo

What I found most interesting while building it was not simply using AI for image processing.

The part I wanted to explore was:

Can AI handle the tedious creation process, while the finished character remains editable and runs without AI?

That became the main design idea behind ChibiRigKit.

The basic workflow

The workflow looks roughly like this:

One character image
        ↓
AI-assisted preparation
        ↓
Separate parts and animation assets
        ↓
Generate an editable 2D rig
        ↓
Adjust it in the browser
        ↓
Export WebM / JSON / ZIP
Enter fullscreen mode Exit fullscreen mode

A normal character illustration can be used as the starting point.

During creation, ChibiRigKit prepares things such as:

  • face layers
  • eyes
  • pupils
  • hair
  • clothing
  • face background layers
  • closed-eye variants
  • closed-mouth variants

The generated character can then be opened in a browser and adjusted interactively.

AI is used during creation, not at runtime

This is probably my favorite part of the architecture.

ChibiRigKit uses Codex CLI during the automatic creation process.

AI helps with tasks such as:

  • analyzing the source image
  • separating character parts
  • creating missing visual information
  • preparing expression variants
  • adjusting positions
  • validating the result

But once the character has been created, Codex is no longer required to play or adjust it.

The generated character runs using regular browser technology.

Conceptually, it looks like this:

Codex / AI
    ↓
creation pipeline

HTML + JavaScript + assets
    ↓
runtime
Enter fullscreen mode Exit fullscreen mode

I didn't want the finished character to depend on an AI service just to blink or move its head.

That means the AI can change, disappear, become more expensive, or be unavailable, while an already-created character can still continue to work.

For this project, AI is closer to a creation tool than a runtime dependency.

Why not fully automate everything?

Because character illustrations are messy.

Two images can have completely different structures.

For example:

  • bangs may cover the eyes
  • accessories may overlap the hair
  • hands may cover the face
  • the character may be heavily stylized
  • important parts may not exist in the original image because they are hidden

Even when AI gets 90% of the result right, I may still want to move one eye by a few pixels.

So instead of treating manual correction as a failure, I designed it as part of the workflow.

The idea is:

AI generates a good starting point
                +
human adjusts the final appearance
Enter fullscreen mode Exit fullscreen mode

The browser UI exposes controls for the parts that are likely to need adjustment.

Head movement without building a full 3D model

One of the more difficult problems was head rotation.

Simply rotating a flat head image works, but it quickly looks like exactly what it is:

a flat image being rotated.

I didn't want to reconstruct a complete 3D head either.

ChibiRigKit instead uses nine reference face configurations:

top-left     top     top-right

left        center      right

bottom-left bottom  bottom-right
Enter fullscreen mode Exit fullscreen mode

The animation interpolates between these configurations.

Each direction can also be edited manually in the browser.

This makes it possible to approximate changes in facial structure while keeping the character fundamentally 2D.

The character is not secretly a full 3D model.

It is still a 2D illustration, but with enough structural information to create a stronger sense of depth.

A shared head mesh

The face, head outline, hair, and accessories can share a parent head mesh.

The head rotates around the neck using:

  • Yaw — looking left/right
  • Pitch — looking up/down
  • Roll — tilting the head

Inside that larger movement, smaller components such as the eyes and mouth can still move independently.

That separation turned out to be important.

Eyes, face, head, and hair shouldn't all move together

Natural-looking idle animation is easier when different motion systems have different behavior.

For example:

Head      → slow movement
Face      → subtle movement
Eyes      → smaller, faster changes
Blinking  → independent timing
Hair      → delayed / softer motion
Enter fullscreen mode Exit fullscreen mode

So ChibiRigKit lets these systems be adjusted separately.

You can make a character whose head barely moves while their eyes move frequently, or do the opposite.

The browser UI includes controls for motion amount, speed, eye movement, blinking, and head rotation.

The browser became both the editor and the runtime

I considered making a native GUI application.

Instead, I ended up using the browser for both editing and playback.

That turned out to be convenient for a few reasons.

UI is easy to build

Sliders, checkboxes, file inputs, and live previews are straightforward.

Changes are visible immediately

The editor and the renderer live in the same environment.

The finished result is portable

A generated character can contain files like:

index.html
assets/
rig.project.json
motion.json
head-poses.json
background.json
Enter fullscreen mode Exit fullscreen mode

Opening index.html is enough to display the finished character.

Saving motion separately

Motion settings can be exported as:

motion.json
Enter fullscreen mode Exit fullscreen mode

Head pose adjustments are stored separately in:

head-poses.json
Enter fullscreen mode Exit fullscreen mode

Background configuration is also kept separately.

So the project is roughly divided into:

character structure
+
motion configuration
+
head poses
+
background
Enter fullscreen mode Exit fullscreen mode

I like this better than baking every decision permanently into one generated file.

The data remains editable.

Exporting a finished character

ChibiRigKit can export a ZIP containing the files needed to replay and adjust a finished character.

For example:

index.html
assets/
rig.project.json
motion.json
head-poses.json
background.json
README.txt
LICENSE.txt
Enter fullscreen mode Exit fullscreen mode

This is intentionally different from the original creation workspace.

The exported ZIP contains the finished runtime character, not all of the AI work history, masks, input material, or Python tooling used to create it.

I wanted a clear separation between:

creation project
!=
finished artifact
Enter fullscreen mode Exit fullscreen mode

Recording directly to WebM

The browser UI can also record the animation directly as WebM.

Recording duration can be set from 1 to 60 seconds.

During recording, the interface shows progress such as:

Recording 12.3 / 30.0 seconds
Enter fullscreen mode Exit fullscreen mode

The recording automatically stops when the selected duration is reached.

Transparent backgrounds are also supported, although transparency support naturally depends on whatever software is used later to play or edit the video.

Getting started

ChibiRigKit currently expects:

  • Python 3.12+
  • Node.js 22+
  • Codex CLI
  • Google Chrome

On macOS:

sh SETUP.command
Enter fullscreen mode Exit fullscreen mode

Then a character can be created with:

sh AUTO_RIG.command "/Users/yourname/Pictures/character.png"
Enter fullscreen mode Exit fullscreen mode

For Linux / macOS with sh:

sh AUTO_RIG.sh "/home/yourname/Pictures/character.png"
Enter fullscreen mode Exit fullscreen mode

A PowerShell version is also included for Windows:

.\AUTO_RIG.ps1 "C:\Users\yourname\Pictures\character.png"
Enter fullscreen mode Exit fullscreen mode

The Windows scripts are included, although the complete workflow has not yet been tested end-to-end on a Windows machine.

Generated characters are placed under:

characters/
Enter fullscreen mode Exit fullscreen mode

More detailed instructions are available in the repository README.

https://github.com/milkc0de/ChibiRigKit

The interesting part: AI-generated intermediate representations

While building this, I started thinking that one of the more useful ways to integrate AI into creative software is not:

prompt
↓
final output
Enter fullscreen mode Exit fullscreen mode

but rather:

prompt / source material
        ↓
AI
        ↓
editable intermediate representation
        ↓
traditional tools
        ↓
human adjustment
        ↓
final output
Enter fullscreen mode Exit fullscreen mode

For ChibiRigKit, that intermediate representation includes things like:

rig.project.json
motion.json
head-poses.json
assets/
Enter fullscreen mode Exit fullscreen mode

Because the AI produces structured, editable output instead of a single final image, both humans and normal software can continue working with it.

That feels much more useful to me for creative workflows.

AI doesn't need to replace the editor

Another thing I learned from this project is that not every part of a workflow benefits from being controlled by AI.

AI is useful for:

  • analyzing complicated visual input
  • generating starting assets
  • repetitive preparation work
  • filling missing information
  • trying multiple adjustments

But a person is still very good at answering questions like:

  • Does this movement look cute?
  • Is the hair moving too much?
  • Should this eye be two pixels further left?
  • Does this still look like the original character?

So ChibiRigKit intentionally returns control to a normal UI after the automated stage.

I think this hybrid approach is more interesting than trying to make every interaction a prompt.

What's next?

There are still plenty of difficult cases.

Complex hair, accessories, unusual poses, and heavily stylized characters can require manual correction.

Large head rotations are also naturally limited by information that simply does not exist in the original 2D image.

So I want to improve both sides of the system:

better automatic generation
+
easier manual correction
Enter fullscreen mode Exit fullscreen mode

The goal isn't necessarily to eliminate human editing completely.

It's to eliminate as much boring preparation work as possible.

Source code

ChibiRigKit is open source under the MIT License.

GitHub:

https://github.com/milkc0de/ChibiRigKit

Building it started as a simple attempt to make one illustration move.

It ended up becoming an experiment in how AI can participate in a creative pipeline without becoming the entire pipeline.

And honestly, seeing a static character image start blinking, looking around, and moving its hair is still pretty fun. 🎀

Top comments (0)