RedCarpG/live2d-vrm-animation

Live2D / VRM Animación de Personajes

Este skill proviene de una mascota de escritorio que soporta tanto personajes Live2D como VRM (ver 'Origen y mantenimiento' al final). Los modelos utilizados incluyen ejemplos oficiales, modelos de VTube Studio y VRM convertidos desde VRChat. Los siguientes procedimientos han sido probados, medidos o revisados por usuarios.

Tres principios que aplican a ambos tipos de personajes

1. La capa procedimental y los clips de animación se sobrescriben mutuamente. Quién escribe primero y quién después en cada fotograma determina lo que ve el usuario. Casi todos los problemas de 'parpadeo', 'manos que caen' o 'cabeza que no se mueve' se originan aquí:
   • Live2D: Los valores superpuestos procedimentalmente se colocan en beforeModelUpdate, y no afectan a la física; el pelo y el cuerpo no se mueven con ellos. Hay que envolver physics.evaluate y superponer antes de la física.
   • VRM: El AnimationMixer de three.js no escribe en los huesos si el valor mezclado en un fotograma es igual al del fotograma anterior. La postura procedimental (de pie, respiración) que se aplica cada fotograma se filtra desde los clips que se han 'detenido'. Hay que saltarse los huesos que están siendo escritos por el clip activo (según los nombres de nodo en clip.tracks). Al pausar, también hay que detener la reescritura procedimental de la postura.
2. No modifiques los archivos de animación; añade una capa procedimental detrás. Las animaciones hechas a mano (keyframes) o por IA suelen mover solo unos pocos huesos (una mano que saluda solo mueve el brazo), pareciendo marionetas. Añadir una capa procedimental 'dinámica' (que eleve el hombro, ceda el torso, retrase la muñeca y la cabeza medio tiempo) después del fragmento, sin superponer los huesos que el fragmento ya escribe, funciona de una vez para todas las animaciones y se puede activar/desactivar para comparar.
3. La verificación se hace contando fotograma a fotograma, no mirando. Los problemas de animación duran uno o dos fotogramas y son difíciles de confirmar a simple vista. Registra el valor de ese hueso (parámetro) en el momento en que se pinta (después de render, o leyendo en beforeModelUpdate de Live2D), compara antes y después de la corrección, y luego haz capturas de pantalla en dos modelos diferentes.

Cuándo leer qué

Lo que quieres hacer	Lee
Live2D: carga, escritura de parámetros, física, idle, acciones, bloqueo, expresiones	references/live2d.md
VRM: postura procedimental y clips, capa dinámica, clips de captura de movimiento, expresiones, SpringBone, ventana transparente	references/vrm.md
VRM: acción con expresión, formas de manos y muñecas, mano tocando el cuerpo (IK), interrupción sin soltar la mano, límites de piernas, ojos que siguen la cabeza, interpolación de keyframes y segmentación	references/vrm.md secciones 19–31
Hacer que la IA genere o modifique expresiones y acciones	references/ai-motion.md
Asentir con la música, mover la cabeza al hablar	references/live2d.md sección 16, references/vrm.md 'Seguir el ritmo'

Los pitfalls más frecuentes (consulta primero estas secciones)

Fenómeno	Causa	Solución
Live2D reporta 'Could not find Cubism runtime' o no se dibuja	Orden de carga incorrecto	Cubism Core → registrar módulo del pipeline de render → PixiJS Application.init() → modelo
Live2D escribe parámetros y lee 58, null u otros valores raros	Se ha pasado el ID como string directamente	Usar primero internalModel.getIdSafe(name) para obtener el handle
Live2D la cabeza no sigue el movimiento (modelo VTube Studio)	ParamAngle* es salida de física y se sobrescribe al escribirlo	Leer physics3.json, reescribir en su parámetro de entrada
Live2D solo la cabeza se mueve, el pelo y el cuerpo no	La superposición se ha colocado después de la física	Envolver physics.evaluate, añadir antes de ella
Live2D el personaje se queda quieto	Los modelos VTube Studio no tienen un Idle decente	Idle procedimental: cabeza, tres senos lentos + respiración, solo escribir parámetros estándar
Live2D stopAllMotions y luego se mueve solo	El motor detecta que no hay acción y reproduce Idle de nuevo	Apuntar motionManager.groups.idle a un grupo inexistente y luego detener breath
VRM la mano de una animación K se suelta al detenerse, parpadea al inicio/final	El mixer no escribe valores no cambiados, la postura procedimental se filtra	La postura procedimental salta los huesos que escribe el clip
VRM una acción de un solo uso salta un fotograma al final	clampWhenFinished=false hace que el mixer cierre la acción antes de finished	clampWhenFinished = true, luego fadeOut
VRM la captura de movimiento (mocap) se para muy abierta, se mueve al inicio, la falda se levanta	El clip trae caderas y piernas	Al convertir, eliminar los tracks de caderas y piernas, usar solo la parte superior
VRM la falda se clava en los muslos, la línea de ayuda de colisión solo muestra una o dos esferas	Los cuerpos de colisión no están registrados en el grupo de colisión de la cadena de resortes (three-vrm solo reconoce los registrados)	Según el esqueleto estándar, añadir cápsulas de pierna a la cadena debajo de la cadera; que la cadera no salte un fotograma (references/vrm.md sección 15)
VRM la expresión escrita en el clip no se ve	La expresión de estado, el parpadeo y la forma de la boca de cada fotograma la sobrescriben	El clip solo escribe huesos
La expresión no se ve en tamaños pequeños	El archivo de expresión solo modifica una pequeña zona	Superponer una capa adicional de parámetros para cada emoción (ojos entrecerrados, sonrojo, inclinación de cabeza, comisura de labios)
VRM al hacer una acción, la cara no tiene expresión	La expresión solo sigue al estado, la acción no la arrastra	Junto a la acción, escribir mood + beats, mezclar según el peso de la acción (references/vrm.md sección 25)
La acción necesita cerrar los ojos o abrir la boca, pero el propio 'cansancio' o 'sonrisa' del modelo lo bloquea	La expresión tiene overrideBlink / overrideMouth que son bloqueos	En ese momento, suprimir esas expresiones (sección 26)
VRM el parpadeo de un solo ojo no se ve	blinkLeft/blinkRight no están vinculados a las claves de forma	Sustituir por un entrecerrar ambos ojos (sección 27)
VRM una acción interrumpe a otra, la mano cae y luego se levanta	La nueva acción comienza desde la postura de pie, la transición de fundido cruzado pasa por esa postura	Empezar desde el momento de la nueva acción que más se parezca al estado actual + transición desde el momento de la interrupción (sección 19)
VRM dedos de la mano rígidos o puño cerrado en mocap; dedos siempre medio flexionados en animación K	Los dedos redirigidos / la acción no escribe los dedos	Quitar los dedos de la mocap, escribir la forma de la mano en la acción (secciones 22, 23)
Apoyar la mejilla, tapar la boca, hacer un corazón no acierta con otro cuerpo	Solo se escribe el ángulo	Calcular el objetivo según huesos y malla en tiempo real, usar IK de dos segmentos (sección 24)
Al final del baile, el pie salta un fotograma	El IK de la pierna toma el control en el mismo fotograma en que comienza el fundido de salida	El IK debe incorporarse gradualmente según el peso de la acción que lleva las piernas (sección 20)
Rodillas semiflexionadas, piernas relajadas con demasiada flexión	Varias capas de desplazamiento de cadera se superponen	Límite de rodilla, reducir cadera a la mitad; levantar talón provoca más flexión (sección 21)
VRM los ojos miran fijamente a la cámara	lookAt apunta a la cámara, al girar la cabeza los ojos giran en sentido contrario	Al girar la cabeza, la mirada sigue a la cabeza, parpadeo al girar, micro-movimientos oculares (sección 28)
La animación K se entrecorta, no es fluida	Cada segmento de keyframes tiene entrada y salida lentas, cada keyframe tiene velocidad 0	Spline cúbico monótono + keyframes desfasados en cada segmento (sección 29)
Estirarse, levantar el brazo barriendo los lados hacia arriba / extender hacia los lados	Faltan los segmentos de cerrar puño, antebrazo doblado; la torsión y la elevación no están separadas	Rehacer por segmentos, la torsión solo en el momento del marco de la puerta (sección 30)
Al cambiar el peso de apoyo en reposo, la parte superior se inclina toda hacia un lado	El límite de rodilla reduce la inclinación de la cadera, pero la cintura y el pecho aún giran en sentido inverso completo	Añadir la parte de inclinación que falta de la cadera a la cintura (sección 31)

Origen y mantenimiento

• Origen: Cirra (mascota de escritorio IA, RedCarpG/cirra-deskpet), de octubre a noviembre de 2026.
  • Código Live2D: src/pet/live2d.ts, src/pet/live2d-physics.ts, src/pet/cubism-core.ts; librería de renderizado untitled-pixi-live2d-engine 1.4.0 (PixiJS 8).
  • Código VRM: src/pet/vrm.ts, src/pet/vrm-motion.ts, desde el 2026-11-11 también vrm-face.ts, vrm-hands.ts, vrm-blend.ts, vrm-reach.ts, vrm-gaze.ts; commits 2b6ab57 (clampWhenFinished), e5e8687 (no usar combineSkeletons).
  • Documentación: docs/stage5.md, docs/live2d-motions.md, docs/live2d-common-motions.md, docs/live2d-studio.md, docs/loop-motions.md, docs/expression-outfit-split.md, docs/music.md, docs/vrm.md, docs/vrm-motion.md, docs/vrm-motion-library.md, docs/vrm-studio.md, docs/vrm-toon.md, docs/beat-tracking.md, docs/vrm-skirt.md, docs/vrm-motion-polish.md.
  • Experiencia: lessons/live2d-motion.md y lessons/threejs-vrm-animation.md en un repo privado.
• Repositorio fuente: skills/live2d-vrm-animation/ en RedCarpG/redcarpg-skills. Las copias en ~/.claude/skills/ son instalaciones locales, no deben modificarse directamente. El código en Cirra es la fuente, no se sincronizan automáticamente.
• Cómo modificar:
  • Realiza los cambios en redcarpg-skills, mediante PR; incrementa la versión en manifest.json, pasa node scripts/validate.mjs y luego publica una release (tag live2d-vrm-animation-v<version>), y reinstala la copia local. Primero revisa los dos archivos de lecciones anteriores para ver si hay nuevas entradas que incorporar.
  • Después de actualizar three.js, three-vrm o la librería de renderizado Live2D, los comportamientos internos de la tabla 'pitfalls más frecuentes' relacionados con la librería (mixer no escribe valores no cambiados, clampWhenFinished, shouldRequestIdleMotion, orden de carga) deben verificarse de nuevo.
  • Los fenómenos observados en un solo modelo deben etiquetarse con el tipo de modelo, no generalizarse como regla universal.
• Historial de actualizaciones:
  • 2026-11-12 · 1.0.0, trasladado a redcarpg-skills para publicación pública. Se eliminaron rutas absolutas locales, el proyecto fuente se enlaza; el contenido no cambia.
  • 2026-11-10 · Cirra · Versión inicial: tres principios, tabla rápida de pitfalls; tres referencias (Live2D, VRM, generación de IA); dos prompts de prueba en evals/.
  • 2026-11-10 · Cirra · Modificación de la sección 15 de VRM (falda atravesando): lo que antes decía 'conviértelo en cápsula y listo' no funcionó, se reemplazó por registro en grupo de colisión, cápsula de pierna genérica y salto de cadera (tres puntos); se añadió una línea a la tabla de pitfalls.
  • 2026-11-10 · Cirra · Sección 15: añadido que el pelo largo se mete en las mangas (la cápsula del brazo no puede replegarse) y que la ropa que sobresale es un problema de skinning.
  • 2026-11-10 · Cirra · references/vrm.md: añadido 'el esqueleto normalizado de VRM 0.x mira hacia -Z' (la postura procedimental cambia la orientación, al girar no hay que anular rotateVRM0; commit e2e6c0c, src/pet/vrm-basis.ts).
  • 2026-11-11 · Cirra · references/vrm.md: añadidas las secciones 19–28 (interrupción sin soltar mano, transición de IK en piernas al fundido, límite de rodilla y levantamiento de talón, dedos de mocap a forma de mano, formas de mano y muñeca, IK de mano tocando cuerpo, acción con expresión, override que bloquea beats, parpadeo de un solo ojo vacío, ojos que siguen la cabeza); sección 11 redirigida a la 25; ai-motion.md: formato y validación para face, hands, reach; se añadieron 9 filas a la tabla de pitfalls. Fuente: docs/vrm-motion-polish.md §10, §11, src/pet/vrm-face.ts, vrm-hands.ts, vrm-blend.ts, vrm-reach.ts, vrm-gaze.ts, vrm-clip-extras.ts, vrm-pose.ts, sidecar/src/shared/motion-face.ts, motion-hands.ts (commits fusionados b2f115d, ea3be9e).
  • 2026-11-11 · Cirra · references/vrm.md: añadidas las secciones 29–31 (keyframes con entrada y salida lentas en cada segmento causan entrecortamiento → spline cúbico monótono y keyframes desfasados; segmentación de estiramiento y torsión del brazo; límite de rodilla reduce inclinación de cadera, causando torso inclinado); se añadieron 3 filas a la tabla de pitfalls. Fuente: docs/vrm-motion-polish.md §12, smoothAt en src/vrm-studio/motion-spec.ts, src/pet/vrm-pose.ts (commit fusionado c5b4728).
  • 2026-11-11 · Cirra · references/live2d.md sección 21: añadidas las dos categorías de exclusión para modelos VTube Studio (entradas físicas, parámetros faciales sin Param), para que las expresiones faciales no cedan al asentir. Fuente: standardInputs e isStandardParam en src/pet/clash.ts, docs/expression-clash.md (commit 7721742).