live2d-halfbody

Half-body Avatar: From One Illustration to VTube Studio

For people who don't want to manually model or adjust meshes. From one character illustration or a text description, the Agent step by step builds a half-body Live2D avatar for VTS. The user only does three things:

1. Confirm the illustration (Step 1);
2. Agree to send the illustration to See-through (Step 3, Hugging Face, backup ModelScope);
3. Check the result in VTS, reply Pass or Fail: <issue> (Step 5).

The Agent does the rest and self-checks before handing it over.

Features Included in One Run

Feature	Driver
Head turn left/right, up/down (±30), body tilts when leaning head	Camera
Body follow: turn, lean, breathing	Camera, VTS Auto-Breath
Blink, single-eye blink (uses drawn closed eye when closing fast); half-closed eyes fade the crease	Camera (separate left/right eye)
Eye tracking, eyebrow movement	Camera
Mouth speech, smile	Camera
Segmented hair swing: bangs (optional), sides (three segments from root to tip, each segment delays after the previous; can be tucked behind ears), back hair or bun; vertical bounce when nodding. For twintails, each tail swings independently from the tie, also in three segments. Hair below shoulders follows the body	Physics
Accessory (necklace pendant, earrings) swing	Physics
Glasses follow face rotation	Camera
Expressions: Smile Eyes N1, O-Mouth N2, Angry Eyes N3, Troubled N4, Clear N0	Hotkey
Gestures: Wave N5, Explain N6, Point N7	Hotkey (also has camera gestures, see Known Issues)
Blush N8	Hotkey

Not possible: large-angle head turns (requires side-face assets), full body, continuous arm movement with camera (requires segmented arm assets). Output is a .moc3 file directly usable in VTS, not a Cubism Editor project file (.cmo3); it cannot be opened in Editor. For refined results (more detailed physics, more expressions, commercial-grade meshes), import layers from layers-st/ into Cubism Editor and re-rig.

Folder Structure

素材/CharacterName/         Illustration, prompts, variants, See-through result, layers
  A0-base.png              Finalized illustration
  prompts/                 Copied from references/prompts/standard, with [[…]] filled in
  check/                   Alignment check images for each variant
  seethrough.psd           Raw result from See-through
  seethrough/              Split into one PNG per layer
  layers/                  Self-split layers: only used as base for See-through compositing, not delivered separately
  layers-st/               Final layers (See-through composited, includes gestures and blush)
  R0-rest.png              Static composited final layers, base for gesture and blush variants
角色/CharacterName/
  character.json           Positions, ranges, layer mappings
  标注.png                 Positions from character.json drawn on the illustration
  素材检查/  prepared/  build/runtime/  自查/  vts/

Steps

All commands run in the user's working directory (where 素材/, 角色/ are located). Prepend PYTHONPATH=<skill directory> (e.g., ~/.claude/skills/live2d-halfbody) so Python can find rigkit.

0. Check Environment

python -m rigkit.doctor

Fix any ✗ items first, otherwise you'll get stuck after generating about 20 images. ! items only affect some features: no See-through token may exhaust anonymous quota, no ffmpeg prevents self-check videos, no Codex uses other image tools for generation (see Step 2).

1. Illustration — User Confirmation

Copy the entire references/prompts/standard/ to 素材/CharacterName/prompts/. First fill in the [[…]] in A0-base.txt (appearance, bangs, side hair, hair length, glasses, earrings).

• Only description: Fill in according to the description, generate the illustration.
• Have an illustration: Save it as 素材/CharacterName/参考.png, attach it as a reference during generation to get a version that meets the rigging requirements (neck visible; bangs stop above eyebrows; side hair covers from ear to chin, or tucked behind ears; flat lighting, white background, gap between arms and body). If the original image doesn't meet these requirements, direct separation will cause issues when animated.

python -m rigkit.variants 素材/CharacterName A0-base

Without Codex, generate A0 using the alternative method in Step 2. Show the user and only proceed after user confirmation.

If you already have files separated into layers according to the Layer List, skip to Step 4.

2. Generate Images

Replace the remaining [[…]] in prompts/ with this character's description; remove prompts for parts the character doesn't have: hat or headpiece V1, front side hair V2, bangs V3, accessory V9 (also delete that line in S1, see Generation). Then:

python -m rigkit.variants 素材/CharacterName

Generates 13–17 "change one thing in the whole image" variants in sequence, with alignment check images for each. Offset within 4 px and changes only in the intended area pass; otherwise delete and regenerate, max three times per variant. Details in Generation.

Using other image tools (no Codex, or Agent can generate images itself): variants skips images that already exist and only checks them, so you can generate images with another tool first and place them there.

python -m rigkit.variants 素材/CharacterName --list

One image per line: image to attach, prompt file, whether generated. Generate one at a time in order; when the attached image says "not yet", wait for it:

• Use the full text from prompts/<name>.txt, do not rewrite; only attach the listed image, asking the tool to modify it. For A0, attach reference image; if no reference, generate directly.
• The tool must be able to edit images: given an image and a prompt, return the modified image. Tools that can only generate new images from text can only generate A0.
• Save as 素材/CharacterName/<name>.png, same aspect ratio as the attached image. Do not crop, add borders, cut out, or inpaint.
• A0 should be square; if not 1254×1254, resize to that dimension (all previous characters are this size).

After generating a batch, run python -m rigkit.variants 素材/CharacterName to generate check images; pass criteria as above. Same for Step 3's gestures and blush: --list F1-blush P1-wave P2-explain P3-point. No character has been fully completed using tools other than Codex yet.

3. Layer Separation — User Approval for Upload

First, self-split the variants as the base for compositing:

python -m rigkit.split 素材/CharacterName 素材/CharacterName/layers --pad-top 90

Then ask the user if they agree to send the illustration to See-through. After agreement:

python -m rigkit.seethrough fetch 素材/CharacterName/A0-base.png 素材/CharacterName/seethrough
python -m rigkit.seethrough split 素材/CharacterName 素材/CharacterName/layers 素材/CharacterName/layers-st --pad-top 90

fetch first tries Hugging Face; if that fails, switches to ModelScope (--site hf or --site modelscope to specify one), using the highest possible resolution from each. You can also pass a PSD from the web version, ComfyUI, or your own GPU: fetch that.psd 素材/CharacterName/seethrough. When running See-through locally, use --site local: no image transmission, no quota usage (see Environment).

Final layers must go through See-through: self-split layers have jagged edges on movement and incomplete occluded hair, so they are not delivered alone. If no quota is available that day, switch sites, wait until the next day, or use a PSD.

split prints each correction it makes to See-through layers (cropping parts drawn outside, repositioning misplaced accessories, filling in missing parts). See Rules under "See-through Compositing". Check layers-st/拆层总览.png: each layer should contain only its own content; the static composite should differ from the illustration only in art style.

Closed eyes and smiling eyes are self-split. If they bring in adjacent lines or have rough edges, and the same spot is still bad after two attempts, feed those two variants to See-through for separation, then run the above split again—it will use See-through's eyelash layers (Rule 103):

python -m rigkit.seethrough fetch 素材/CharacterName/D5-eyes-closed.png 素材/CharacterName/seethrough-D5-eyes-closed
python -m rigkit.seethrough fetch 素材/CharacterName/D6-eyes-smile.png 素材/CharacterName/seethrough-D6-eyes-smile

Ask the user before sending to the site; each image consumes a quota. When running locally, use --site local --head-from 素材/CharacterName/seethrough to only split the head.

Then generate gestures and blush:

python -m rigkit.extras 素材/CharacterName 素材/CharacterName/layers-st        # Creates R0-rest.png
python -m rigkit.variants 素材/CharacterName F1-blush P1-wave P2-explain P3-point
python -m rigkit.extras 素材/CharacterName 素材/CharacterName/layers-st        # Adds to layers

Check layers-st/手势和脸红.png: each row shows static, variant, and after enabling in the model. Proceed only if the arm connects to the body and hand edges are clean.

4. Generate and Self-Check

python -m rigkit.estimate 素材/CharacterName/layers-st 角色/CharacterName --name Name
python -m rigkit.check_art 角色/CharacterName/character.json
python -m rigkit.prepare 角色/CharacterName/character.json
python -m rigkit.build 角色/CharacterName/character.json             # Takes a few minutes

• estimate does not overwrite an existing character.json; writes character.draft.json. After re-estimating due to changed layers, compare and replace.
• 标注.png: if the face ellipse, eye/eyebrow/nose/mouth, head tilt axis, neck base, shoulders, waist, or hair root line are not in the correct position, change the corresponding numbers in character.json and re-run prepare and build.
• 素材检查/: if 露底 shows magenta, or 原画对照 shows red lines, go back to Step 3. 透出背景 lists areas not covered when static and areas that become transparent during gestures; then check 青底.png (static and each gesture on a cyan background): gaps on white clothes or light skin are invisible on white. Transparency where an arm moves away is normal; anything else, go back to Step 3.

Self-check:

python -m rigkit.preview flips 角色/CharacterName/build/runtime
python -m rigkit.preview sheet 角色/CharacterName/character.json 角色/CharacterName/自查 新版=角色/CharacterName/build/runtime
python -m rigkit.preview clip 角色/CharacterName/character.json 角色/CharacterName/自查/动作.mp4 新版=角色/CharacterName/build/runtime

Flipped triangles should be 0. Check the fixed inspection areas (eyebrows and bangs, face edge, chin and neck, temple and ear, eye corner and eyelashes, mouth corner) in close-up images and the video. If there are issues, fix them first, then hand over to the user. If there is a previous version, place it side by side for comparison.

Also render on VTS background color: closed eyes, half-closed, smiling eyes, large mouth, half-open mouth, three gestures, head shake left and right. Magnify the eye, mouth, and hair boundaries three to four times: these are the first things users see in VTS.

5. Install into VTS — User Acceptance

python -m rigkit.vts 角色/CharacterName/character.json --install

New models can be installed while VTS is running; to overwrite an installed model, VTS must be exited first—this preserves the user's settings in VTS, only adding missing hotkeys and mappings. When VTS is running and you need to install a new version, change vts.name and vts.folder to install as a new folder.

Show the user the side-by-side images, video, and the checklist below. Reply Pass or Fail: <issue>:

What to Check	How to Check
Head turn, tilt	Turn head left/right/up/down, tilt: face, hair, hat, ears follow; no cracks, fragments, or parts left behind
Eyes	Blink, single-eye blink, half-closed; eyelashes do not penetrate hair during turns
Mouth	Speech, smile; mouth doesn't become crooked during head turns while closed
Hair	Shake head: bangs, side hair, back hair swing in segments, each segment delays after the previous; vertical bounce when nodding; long hair follows body below shoulders
Accessories	Pendants swing when body moves; clothing underneath remains intact
Body	Body follow: turn, lean, breathing
Expressions	Switch between N1–N4, N0 clears
Gestures	N5–N7: body art style remains consistent, hand edges clean; when gesturing and turning head, arms follow body
Blush	N8: soft edges; when shaking head, no visible edge below hair

Adjusting Range

All movement ranges are in character.json:

What to Change	Field
Head tilt angle	head.tilt_deg (degrees at full range)
How far the face moves during head turn	head.yaw_px, head.pitch_px
Body tilt	body.tilt_deg (degrees per parameter unit, full range ×10)
Breathing range	body.breath.head, body.breath.shoulder (pixels)
Body follow	body.turn, body.shift, body.lean_y
Hair swing range	hair.locks.<layer>.swing; mid and tip segments hair.locks.<layer>.bend; nod hair.locks.<layer>.pitch
Physics feel	hair.locks.<layer>.chain (three segments) or physics: delay smaller = more drag, length larger = slower
Accessory swing range	dangles.<layer>.deg (degrees at full range)
Half-closed eye	eyes.crease_fade (crease fade range), eyes.lower_from (position where lower eyelid starts closing)
Mouth opening threshold	mouth.open_from: mouth stays closed when camera reading is below this

Ranges are judged based on VTS half-body framing and real human motion: normal head tilt is about 15°, a model that only tilts 3° might as well have none. Rebuild after changing. See Configuration Guide for other fields.

Rules

All rules and their rationale are in Rules. Most frequently violated rules:

• Before starting, look up Live2D standard practices and explain your plan.
• Use See-through for cutting; image models only provide details it cannot (expressions, occluded parts, gestures).
• Only handle what you're confident about: use See-through layers as whole blocks; only do whole-block selection, repositioning, and splitting by disconnected regions; do not do per-pixel color-based cutting within a layer (results in jagged edges). Before modifying a section, compare it side-by-side at high zoom with the See-through original; only modify if clearly better.
• For new rules, first measure the basis on all existing characters, define the scope, run both old and new code and compare layer by layer; do not break already-passing characters. Each rule clearly states its scope: universal, or only triggered under specific conditions (trigger conditions, excluded cases).
• Always provide same-size side-by-side images and video for human judgment; flipped triangle count and pixel differences are only used to detect mesh tearing.
• If the same symptom is not fixed after three rounds of code changes, stop and fix it with assets instead.
• Image models only do "change one thing in the whole image", not "keep only a part"; code extracts parts by difference.
• Ask the user before sending images to external services; accounts and tokens are registered and filled in by the user—do not repeat tokens in conversation.
• Installation does not overwrite the user's vtube.json; VTS must be exited before overwriting an installed model.

Environment

• Python 3.10+: pip install -r <skill directory>/requirements.txt (create a virtual environment if the system Python doesn't allow installation). ffmpeg required for video generation.
• Codex CLI (image generation): comes with ChatGPT Desktop, or standalone installed codex (in PATH); log in to ChatGPT. Otherwise set environment variable CODEX to point to it. Without Codex, use another image editing tool (see Step 2).
• See-through (layer separation). Both sites run the same model; prepare at least one:
  • Hugging Face (preferred, minutes per run, max 1280): free GPU time per day without login may not be enough for one run; user registers a free account, creates a Read token, places it in environment variable HF_TOKEN or ~/.cache/huggingface/token (where hf auth login stores it); about 1–2 runs per day.
  • ModelScope (backup, free, max 1536): user registers an account, creates an access token, places it in environment variable MODELSCOPE_API_TOKEN or ~/.cache/modelscope/token. May be queued; one run could take half an hour. The 1536 resolution gives hair outlines and eyes more faithful to the original artwork than 1280.
  • Local (optional, no image transmission, unlimited runs): verified on Apple Silicon with 24 GB RAM; full 1280 image takes about 21 minutes, head-only about 9 minutes; first run downloads ~13 GB of models. After installation, point environment variable SEETHROUGH_DIR to it; see Generation under "Running See-through Locally".
• VTube Studio (Steam version).
• Live2D Cubism Core (required for preview, self-check, and icons): if Cubism Editor is installed, it's found automatically; otherwise download Cubism SDK for Native and set environment variable CUBISM_CORE to point to the Core dynamic library. Core is used under Live2D's license and is not distributed with this skill.

Verified on macOS; not verified on Windows.

Known Issues

• Camera gestures (open palm = wave, both hands open = explain, index finger = point): the first character can trigger them, but the second character with identical per-field configuration doesn't trigger them. Cause unknown. Hotkeys N5–N7 are unaffected.
• When static, the avatar looks softer than the original illustration; eyelashes and hair outline edges have fewer details.
• When wearing glasses and the frame is very close to the crease, See-through may lose the crease line and draw a light gray band along the upper eyelash line; this is preserved as-is.
• When the outer eye corner is close to the contour line between the cheek and ear (e.g., a beanie), the self-split closed eye and smiling eye layers may include a small piece of this contour line, which appears at the face edge during head turns. Sending these two variants to See-through can remove it (Step 3).