live2d-halfbody

Medio Cuerpo: De una Ilustración a VTube Studio

Para quienes no quieren modelar manualmente ni ajustar mallas. Una ilustración o descripción de personaje, y el Agent crea paso a paso un avatar Live2D de medio cuerpo listo para transmitir en VTS. El usuario solo hace tres cosas:

1. Confirmar la ilustración (paso 1);
2. Aceptar subir la ilustración a See-through (paso 3, Hugging Face, respaldo ModelScope);
3. Ver el resultado en VTS y responder Aprobado o No aprobado: <fenómeno> (paso 5).

El resto lo realiza el Agent, incluida la autoverificación antes de entregar.

Funcionalidades de una sola ejecución

Función	Control
Giro de cabeza izquierda/derecha, arriba/abajo (±30°), inclinación con seguimiento corporal	Cámara
Seguimiento corporal: giro lateral, adelante/atrás, respiración	Cámara, respiración automática VTS
Parpadeo completo y de un ojo (cierre rápido con el ojo cerrado dibujado); al medio cerrar, el párpado doble se desvanece	Cámara (ojos separados)
Seguimiento ocular, cejas arriba/abajo	Cámara
Apertura de boca al hablar, sonrisa	Cámara
Movimiento segmentado del cabello: flequillo (opcional), laterales (tres segmentos, de raíz a punta, uno tras otro; puede ir detrás de la oreja), parte trasera o moño; al asentir, rebote vertical. Coletas: cada una se mueve independientemente desde la goma, también tres segmentos. Cabello largo hasta los hombros sigue el cuerpo	Física
Oscilación de accesorios (colgantes, pendientes)	Física
Gafas siguen el giro de la cabeza	Cámara
Expresiones: Ojos sonrientes N1, Boca en O N2, Ojos serios N3, Preocupado N4, Limpiar N0	Teclas de acceso rápido
Gestos: Saludar N5, Manos abiertas N6, Señalar N7	Teclas de acceso rápido (también con gestos de cámara, ver "Problemas conocidos")
Rubor N8	Teclas de acceso rápido

No se puede: giro amplio de cabeza (necesita material de perfil), cuerpo completo, movimiento continuo de brazos con la cámara (necesita material segmentado). El resultado es .moc3 directamente utilizable en VTS, no un archivo de proyecto de Cubism Editor (.cmo3), no se abre en Editor. Para efectos de nivel detallado (física más fina, más expresiones, malla comercial) se deben importar las capas de layers-st/ a Cubism Editor y reenlazar.

Carpetas

Materiales/NombrePersonaje/         Ilustración, prompt, variantes, resultado See-through, capas
  A0-base.png                       Ilustración final
  prompts/                          Copiado de references/ prompts/estándar/, rellenar [[…]]
  check/                            Imágenes de verificación de cada variante
  seethrough.psd                    Resultado original de See-through
  seethrough/                       Descompuesto en una PNG por capa
  layers/                           Capas auto-descompuestas: solo base para síntesis See-through, no se entregan solas
  layers-st/                        Capas finales (síntesis See-through, incluye gestos y rubor)
  R0-rest.png                       Síntesis estática de las capas finales, base para variantes de gestos y rubor
Personaje/NombrePersonaje/
  character.json                    Posición, amplitud, correspondencia de capas
  etiquetado.png                    Posiciones de character.json dibujadas sobre la ilustración
  chequeoMateriales/  prepared/  build/runtime/  autoverificación/  vts/

Pasos

Los comandos se ejecutan en el directorio de trabajo del usuario (donde están Materiales/, Personaje/). Antes del comando se añade PYTHONPATH=<directorio del skill> (p. ej. ~/.claude/skills/live2d-halfbody) para que Python encuentre rigkit.

0. Verificar entorno

python -m rigkit.doctor

Si hay ✗, resolverlos antes de generar imágenes; de lo contrario, se atascará después de generar unas veinte imágenes. ! solo afecta parcialmente: sin token de See-through, la cuota anónima puede no ser suficiente; sin ffmpeg, no se puede generar el video de autoverificación; sin Codex, se usan otras herramientas de imagen (ver paso 2).

1. Ilustración — Confirmación del usuario

Copia todo references/ prompts/estándar/ a Materiales/NombrePersonaje/prompts/. Primero rellena los [[…]] en A0-base.txt (apariencia, flequillo, cabello lateral, largo, gafas, pendientes).

• Solo descripción: rellena según la descripción, genera la ilustración.
• Con ilustración: guarda como Materiales/NombrePersonaje/referencia.png, se adjunta como imagen de referencia al generar, obteniendo una versión dibujada según los requisitos de enlace (cuello visible; si hay flequillo, termina por encima de las cejas; cabello lateral cubre desde la oreja hasta la barbilla, o detrás de la oreja; luz plana, fondo blanco, espacio entre brazo y cuerpo). Si la imagen original no cumple estos requisitos, la descomposición directa causará problemas al moverse.

python -m rigkit.variants Materiales/NombrePersonaje A0-base

Sin Codex, genera A0 según "Generar imágenes con otras herramientas" del paso 2. Mostrar al usuario; solo continuar tras confirmación.

Si ya se tienen archivos con capas separadas según la Lista de capas, saltar al paso 4.

2. Generar imágenes

Reemplaza los [[…]] restantes en prompts/ con la descripción de este personaje; elimina los prompts de componentes que el personaje no tiene: sombrero o tocado V1, cabello frontal lateral V2, flequillo V3, accesorio colgante V9 (en S1 también elimina esa línea, ver Generar imágenes). Luego:

python -m rigkit.variants Materiales/NombrePersonaje

Genera de 13 a 17 variantes "una cosa cambiada en toda la imagen", cada una con su imagen de verificación. Desplazamiento dentro de 4 px, cambio solo en la zona prevista: se considera aprobado; si no, se elimina y se regenera, máximo tres veces por variante. Detalles en Generar imágenes.

Generar imágenes con otras herramientas (sin Codex, o si el Agent puede generar imágenes por sí mismo): variants solo verifica las imágenes ya existentes, no las regenera, por lo que se pueden generar las imágenes con otra herramienta y colocarlas.

python -m rigkit.variants Materiales/NombrePersonaje --list

Una imagen por línea: imagen a adjuntar, archivo de prompt, si ya se generó. Generar una por una en orden; cuando la imagen adjunta dice "aún no", esperar a que esté lista:

• El prompt usa el texto completo de prompts/<nombre>.txt, sin reescribir; solo adjuntar la imagen indicada, para que la herramienta la modifique a partir de ella. A0 adjunta la imagen de referencia; sin ella, se genera directamente.
• La herramienta debe poder modificar imágenes: dadas una imagen y un prompt, devolver la misma imagen modificada. Herramientas que solo generan imágenes desde texto solo pueden generar A0.
• Guardar como Materiales/NombrePersonaje/<nombre>.png, con la misma relación de aspecto que la imagen adjunta. No recortar, no añadir bordes, no recortar fondo, no reparar.
• A0 se genera en cuadrado; si no es 1254×1254, redimensionar a ese tamaño (todos los personajes hechos tienen este tamaño).

Después de generar un lote, ejecutar python -m rigkit.variants Materiales/NombrePersonaje para generar las imágenes de verificación. El estándar de aprobación es el mismo. Los gestos y rubor del paso 3 también: --list F1-blush P1-wave P2-explain P3-point. Aún no se ha completado un personaje completo con herramientas distintas a Codex.

3. Descomposición de capas — El usuario acepta la subida

Primero, auto-descomposición de las variantes como base para la síntesis:

python -m rigkit.split Materiales/NombrePersonaje Materiales/NombrePersonaje/layers --pad-top 90

Luego preguntar al usuario si acepta subir la ilustración a See-through. Si acepta:

python -m rigkit.seethrough fetch Materiales/NombrePersonaje/A0-base.png Materiales/NombrePersonaje/seethrough
python -m rigkit.seethrough split Materiales/NombrePersonaje Materiales/NombrePersonaje/layers Materiales/NombrePersonaje/layers-st --pad-top 90

fetch primero intenta Hugging Face; si falla, cambia a ModelScope (--site hf o --site modelscope para especificar uno), usando la resolución más alta disponible. También se puede pasar un PSD generado por la versión web, ComfyUI o la propia GPU: fetch ese.psd Materiales/NombrePersonaje/seethrough. Si se tiene See-through instalado localmente, usar --site local: no sube imágenes, no consume cuota (ver "Entorno").

Las capas finales deben pasar por See-through: las capas auto-descompuestas tienen bordes pixelados al moverse y el cabello oculto no se completa, no se entregan solas. Si no hay cuota ese día, cambiar al otro sitio, esperar al día siguiente, o usar un PSD.

split imprimirá una por una las correcciones que hace a las capas de See-through (recortar lo que se dibujó fuera, mover accesorios mal posicionados, completar componentes omitidos), reglas en Reglas en "Síntesis See-through". Ver layers-st/VistaGeneralDescomposicion.png: cada capa solo contiene su propio elemento; la síntesis estática y la ilustración solo difieren en el estilo.

Los ojos cerrados y ojos sonrientes se auto-descomponen. Si arrastran líneas adyacentes o bordes irregulares, y después de dos intentos de corrección aún persisten, pasar esas dos variantes a See-through y ejecutar de nuevo el split anterior; usará las capas de pestañas de See-through (regla 103):

python -m rigkit.seethrough fetch Materiales/NombrePersonaje/D5-eyes-closed.png Materiales/NombrePersonaje/seethrough-D5-eyes-closed
python -m rigkit.seethrough fetch Materiales/NombrePersonaje/D6-eyes-smile.png Materiales/NombrePersonaje/seethrough-D6-eyes-smile

Subir al sitio también pregunta primero al usuario; cada imagen consume una cuota. Al ejecutar localmente, añadir --site local --head-from Materiales/NombrePersonaje/seethrough, solo descompone la cabeza.

Luego hacer gestos y rubor:

python -m rigkit.extras Materiales/NombrePersonaje Materiales/NombrePersonaje/layers-st        # Genera R0-rest.png
python -m rigkit.variants Materiales/NombrePersonaje F1-blush P1-wave P2-explain P3-point
python -m rigkit.extras Materiales/NombrePersonaje Materiales/NombrePersonaje/layers-st        # Añade a las capas

Ver layers-st/GestosYRubor.png: cada fila muestra estado estático, variante, y cómo se ve al activarse en el modelo. Solo continuar si el brazo y el cuerpo conectan y los bordes de la mano están limpios.

4. Generar y autoverificar

python -m rigkit.estimate Materiales/NombrePersonaje/layers-st Personaje/NombrePersonaje --name Nombre
python -m rigkit.check_art Personaje/NombrePersonaje/character.json
python -m rigkit.prepare Personaje/NombrePersonaje/character.json
python -m rigkit.build Personaje/NombrePersonaje/character.json             # Unos minutos

• estimate no sobrescribe character.json existente, escribe character.draft.json; si se modificaron capas y se necesita reestimar, comparar y reemplazar.
• etiquetado.png: si la elipse de la cara, cejas, nariz, boca, eje de inclinación, base del cuello, hombros, cintura, línea de raíz del cabello no están en la posición correcta, modificar los números correspondientes en character.json, luego rehacer prepare y build.
• chequeoMateriales/: si FondoVisible tiene magenta, o ComparaciónOriginal tiene líneas rojas, volver al paso 3. FondoTransparente lista las zonas no cubiertas en estático y las que se vuelven transparentes en gestos; luego ver FondoCian.png (estático y cada gesto sobre fondo cian): las zonas blancas o de piel clara no se notan en fondo blanco. Los huecos al mover el brazo son normales; el resto, volver al paso 3.

Autoverificación:

python -m rigkit.preview flips Personaje/NombrePersonaje/build/runtime
python -m rigkit.preview sheet Personaje/NombrePersonaje/character.json Personaje/NombrePersonaje/autoverificación nuevaVersion=Personaje/NombrePersonaje/build/runtime
python -m rigkit.preview clip Personaje/NombrePersonaje/character.json Personaje/NombrePersonaje/autoverificación/accion.mp4 nuevaVersion=Personaje/NombrePersonaje/build/runtime

Los triángulos invertidos deben ser 0. Revisar en la imagen ampliada y en el video las zonas de verificación fijas (cejas y flequillo, borde de la cara, barbilla y cuello, sien y oreja, comisura del ojo y pestañas, comisura de los labios). Si hay problemas, corregir antes de entregar al usuario. Si existe una versión anterior, colocarla al lado para comparar.

Luego, sobre el fondo de VTS, renderizar cada uno: ojos cerrados, medio cerrados, sonrientes, boca abierta grande, medio abierta, tres gestos, giro de cabeza izquierda/derecha. Ampliar de 3 a 4 veces las zonas de los ojos, boca y cabello: son las primeras imágenes que el usuario verá en VTS.

5. Instalar en VTS — Aprobación del usuario

python -m rigkit.vts Personaje/NombrePersonaje/character.json --install

Se puede instalar un modelo nuevo con VTS abierto; para sobrescribir un modelo ya instalado, primero cerrar VTS; entonces se conservan los ajustes que el usuario haya hecho en VTS, solo se añaden las teclas de acceso rápido y mapeos faltantes. Si VTS está abierto y se quiere instalar una nueva versión, cambiar vts.name y vts.folder para instalarlo como una carpeta nueva.

Entregar al usuario la imagen comparativa, el video y la siguiente lista. Responder Aprobado o No aprobado: <fenómeno>:

Qué revisar	Cómo hacerlo
Giro e inclinación de cabeza	Girar la cabeza izquierda/derecha, arriba/abajo, inclinar: cara, cabello, sombrero, orejas giran juntos; sin grietas, puntos sueltos, elementos que se quedan en su sitio
Ojos	Parpadeo completo, de un ojo, medio cerrar; al girar la cabeza, las pestañas no atraviesan el cabello
Boca	Hablar, sonreír; al girar la cabeza con la boca cerrada, la boca no se tuerce
Cabello	Sacudir la cabeza: flequillo, cabello lateral, trasero se mueven por segmentos, de raíz a punta, cada segmento más lento que el anterior; al asentir, rebote vertical; cabello largo sigue el cuerpo por debajo de los hombros
Accesorios colgantes	Al mover el cuerpo, los colgantes oscilan; la ropa debajo permanece completa
Cuerpo	Seguimiento corporal: giro lateral, adelante/atrás, respiración
Expresiones	Cambiar entre N1~N4, N0 limpia
Gestos	N5~N7: el estilo del cuerpo no cambia bruscamente, bordes de la mano limpios; al girar la cabeza con el gesto activo, el brazo sigue el cuerpo
Rubor	N8: bordes suaves; al sacudir la cabeza, el rubor no se ve por debajo del cabello

Ajustar amplitudes

Las amplitudes de movimiento están en character.json:

Qué cambiar	Campo
Ángulo de inclinación	head.tilt_deg (grados en amplitud completa)
Distancia de giro de cabeza	head.yaw_px, head.pitch_px
Inclinación corporal	body.tilt_deg (grados por unidad de parámetro, amplitud completa ×10)
Respiración	body.breath.head, body.breath.shoulder (píxeles)
Seguimiento corporal	body.turn, body.shift, body.lean_y
Amplitud de cabello	hair.locks.<capa>.swing; segmento medio y punta hair.locks.<capa>.bend; asentir hair.locks.<capa>.pitch
Sensación física	hair.locks.<capa>.chain (tres segmentos) o physics: delay menor = más arrastre, length mayor = más lento
Amplitud de colgantes	dangles.<capa>.deg (grados en amplitud completa)
Medio cerrar ojos	eyes.crease_fade (intervalo de desvanecimiento del párpado doble), eyes.lower_from (posición desde donde empieza a cerrar el párpado inferior)
Desde dónde abre la boca	mouth.open_from: cuando la lectura de la cámara es menor, mantener la boca cerrada

La amplitud se juzga según el encuadre de medio cuerpo de VTS y el movimiento humano real: una inclinación normal es de unos 15°; si el modelo solo gira 3°, es como si no tuviera efecto. Después de modificar, rehacer build. Otros campos en Configuración.

Reglas

Todas las reglas y su justificación están en Reglas. Las más frecuentemente violadas:

• Antes de actuar, consultar primero las prácticas estándar de Live2D, explicar claramente cómo se va a hacer.
• Usar See-through para cortar imágenes; el modelo de imagen solo completa los detalles que See-through no puede dar (expresiones, partes ocultas, gestos).
• Solo trabajar con partes seguras: usar las capas de See-through como bloques enteros; el código solo hace selección, movimiento y separación por bloques no conectados, no recortar dentro de sus capas por color píxel a píxel (los cortes serán irregulares). Para modificar algo, primero ampliar y comparar lado a lado con el original de See-through; si no es claramente mejor, no modificar.
• Las nuevas reglas deben medirse primero en todos los personajes existentes, determinar el alcance, y después de modificar, ejecutar tanto el código antiguo como el nuevo para comparar capa por capa, sin dañar a los personajes ya aprobados. Cada regla debe especificar su alcance: general, o solo bajo ciertas condiciones (condiciones de activación, casos que no se consideran).
• Cada ronda entregar imágenes del mismo tamaño lado a lado y un video; que una persona juzgue; el número de triángulos invertidos y la diferencia de píxeles solo se usan para localizar problemas de superficie.
• Si el mismo síntoma persiste después de tres rondas de corrección, dejar de modificar el código y resolver con material.
• El modelo de imagen solo recibe instrucciones "cambiar una cosa en toda la imagen", no "dejar solo una parte"; la parte requerida la calcula el código mediante diferencias.
• Preguntar al usuario antes de subir imágenes a servicios externos; la cuenta y el token los registra y rellena el usuario, no repetir el token en la conversación.
• No sobrescribir el vtube.json del usuario al instalar; para sobrescribir un modelo ya instalado, VTS debe estar cerrado primero.

Entorno

• Python 3.10+: pip install -r <directorio del skill>/requirements.txt (si el sistema no permite instalar, crear un entorno virtual). Para videos se necesita ffmpeg.
• Codex CLI (generar imágenes): viene con la versión de escritorio de ChatGPT, o codex instalado por separado (en PATH); iniciar sesión en la cuenta de ChatGPT; si no, apuntar la variable de entorno CODEX a él. Sin Codex, usar otras herramientas de imagen que puedan modificar imágenes, ver paso 2.
• See-through (descomposición de capas), ambos sitios ejecutan el mismo modelo, preparar al menos uno:
  • Hugging Face (preferido, unos minutos por vez, máximo 1280): sin iniciar sesión, el tiempo gratuito diario de GPU puede no ser suficiente para una ejecución; el usuario se registra gratis, crea un Read token, lo coloca en la variable de entorno HF_TOKEN o en ~/.cache/huggingface/token (donde hf auth login lo guarda), aproximadamente 1~2 veces al día.
  • ModelScope (respaldo, gratuito, máximo 1536): el usuario se registra, crea un token de acceso, lo coloca en la variable de entorno MODELSCOPE_API_TOKEN o en ~/.cache/modelscope/token. Hay cola, puede tomar media hora. El contorno del cabello y los ojos a 1536 se acercan más a la ilustración original que a 1280.
  • Local (opcional, no sube imágenes, sin límite de veces): verificado en Apple Silicon con 24 GB de RAM; imagen completa de 1280 tarda unos 21 minutos, solo la cabeza unos 9 minutos; la primera ejecución descarga aproximadamente 13 GB del modelo. Después de instalar, apuntar la variable de entorno SEETHROUGH_DIR a él; instrucciones de instalación en Generar imágenes en "Ejecutar See-through localmente".
• VTube Studio (versión de Steam).
• Live2D Cubism Core (necesario para vista previa, autoverificación e iconos): si está instalado Cubism Editor, se encuentra automáticamente; de lo contrario, descargar Cubism SDK for Native y apuntar la variable de entorno CUBISM_CORE a la biblioteca dinámica Core. Core se utiliza según la licencia de Live2D, no se distribuye con este skill.

Verificado en macOS; no verificado en Windows.

Problemas conocidos

• Gestos de cámara (mano abierta = saludar, ambas manos abiertas = manos abiertas, dedo índice levantado = señalar): el primer personaje los activa, el segundo con la misma configuración campo por campo no los activa, causa no identificada. Las teclas de acceso rápido N5~N7 no se ven afectadas.
• En estático, el modelo tiene el aspecto del See-through, más suave que la ilustración original, con menos detalles en pestañas y contorno de puntas de cabello.
• Con gafas, si el marco está muy cerca del párpado doble, See-through pierde la línea del párpado doble y dibuja una banda gris clara en el borde superior de las pestañas; se conserva tal cual.
• Cuando la comisura del ojo está cerca de la línea de contorno entre la mejilla y la oreja (gorro de lana), las capas auto-descompuestas de ojos cerrados y sonrientes arrastran un pequeño segmento de esa línea de contorno, que aparece en el borde de la cara al girar la cabeza. Se puede eliminar pasando esas dos variantes a See-through (paso 3).