Live2D / VRM 角色动画

Animation de personnages Live2D / VRM

Ce skill provient d'une mascotte de bureau supportant à la fois les personnages Live2D et VRM (voir « Source et maintenance » en bas). Les modèles utilisés incluent des exemples officiels, des modèles VTube Studio et des VRM convertis depuis VRChat. Les solutions ci-dessous ont toutes été testées, mesurées, ou vues et modifiées par des utilisateurs.

Trois principes transversaux aux deux types de personnages

1. La couche procédurale et les clips d'action se superposent. Qui écrit en premier, qui écrit en dernier chaque frame détermine ce que voit l'utilisateur. Presque tous les problèmes de « scintillement », « bras qui retombent », « tête figée » viennent de là :
   • Live2D : les valeurs procédurales placées dans beforeModelUpdate n'entrent pas dans la physique : cheveux et corps ne suivent pas. Il faut envelopper physics.evaluate et superposer avant la physique.
   • VRM : l'AnimationMixer de three.js n'écrit pas les valeurs sur les os si le résultat mixé est identique à la frame précédente. La pose procédurale (debout, respiration) appliquée chaque frame ressort à travers les parties du clip qui sont « figées ». Il faut sauter les os que le clip en cours écrit (via les noms de nœuds dans clip.tracks). En pause aussi, il faut arrêter la pose procédurale et la réécrire.
2. Ne pas modifier les fichiers d'action, ajouter une couche procédurale par-dessus. Les animations faites à la main ou par IA ne bougent souvent que quelques os (agiter la main ne bouge que le bras), ce qui donne un effet de marionnette. Après le clip, ajouter une couche procédurale de « suivi » (l'épaule se lève, le torse cède, le poignet retarde, la tête suit avec un demi-temps), sans superposer les os déjà écrits par le clip. Fait une fois, tous les mouvements en bénéficient, avec possibilité de comparaison avant/après.
3. La validation se fait image par image, pas à l'œil. Les problèmes d'animation ne durent qu'une ou deux frames, difficiles à confirmer visuellement. Enregistrer frame par frame la valeur de l'os (ou paramètre) au moment où il est dessiné (après le rendu, ou en lisant dans beforeModelUpdate pour Live2D), comparer avant et après correction ; puis faire des captures d'écran sur deux modèles différents.

Quand lire quoi

Ce que vous voulez faire	Lisez
Live2D : chargement, écriture de paramètres, physique, idle, actions, mise en pause, expressions	references/live2d.md
VRM : pose procédurale et clips, couche de suivi, clips de capture de mouvement, expressions, SpringBone, fenêtre transparente	references/vrm.md
VRM : action + expression, formes de main et poignet, main touchant le corps (IK), interruption sans laisser tomber la main, limites des jambes, yeux suivant la tête, interpolation des clés et segmentation	references/vrm.md §19–31
Générer ou modifier expressions et actions par IA	references/ai-motion.md
Hocher la tête en rythme avec la musique, bouger la tête en parlant	references/live2d.md §16, references/vrm.md « Suivre le rythme »

Pièges les plus fréquents (consultez d'abord ceux-ci)

Symptôme	Cause	Solution
Live2D : erreur « Could not find Cubism runtime » ou rien ne s'affiche	Ordre de chargement incorrect	Cubism Core → module d'enregistrement du render pipe → PixiJS Application.init() → modèle
Live2D : lecture de paramètres donne 58, null ou autres valeurs bizarres	ID de chaîne passé directement	Utiliser internalModel.getIdSafe(name) pour obtenir le handle
Live2D : la tête ne suit pas (modèle VTube Studio)	ParamAngle* est une sortie de la physique, écrasée ensuite	Lire physics3.json, écrire sur son paramètre d'entrée
Live2D : seule la tête bouge, cheveux et corps immobiles	Superposition après la physique	Envelopper physics.evaluate, superposer avant
Live2D : personnage immobile	Modèle VTube Studio sans Idle correct	Idle procédural : tête, corps (3 sinusoïdes lentes) + respiration, n'écrire que les paramètres standard
Live2D : stopAllMotions puis le personnage se remet à bouger	Le moteur relance un Idle s'il n'y a pas d'action	Pointer motionManager.groups.idle vers un groupe inexistant, puis arrêter breath
VRM : dans une action main, le bras retombe pendant la pause, scintillement au début/fin	Le mixer n'écrit pas les valeurs inchangées, la pose procédurale de debout réapparaît	La pose procédurale saute les os écrits par le clip
VRM : à la fin d'une action one-shot, retour brusque à la position initiale en une frame	clampWhenFinished=false, le mixer arrête l'action avant finished	clampWhenFinished = true, puis fadeOut
VRM : action de capture de mouvement : jambes écartées, décalage au début, jupe qui vole	Le clip contient les pistes de bassin et jambes	Supprimer les pistes de bassin et jambes lors de la conversion, n'utiliser que le haut du corps
VRM : jupe qui traverse la cuisse, seuls 1–2 spheres de collision visibles	Les colliders ne sont pas enregistrés dans le groupe de collision de la chaîne SpringBone (three-vrm ne reconnaît que ceux enregistrés)	Ajouter des capsules de jambe à la chaîne sous le bassin selon le squelette standard ; ne pas faire sauter le bassin d'une frame (voir references/vrm.md §15)
VRM : les expressions du clip ne s'affichent pas	Les expressions d'état (yeux, bouche, clignement) écrasent chaque frame	Le clip ne doit écrire que les os
Expressions peu visibles à petite taille	Le fichier d'expression ne modifie qu'une petite zone	Ajouter une couche de paramètres supplémentaire (plissement des yeux, rougeur, inclinaison de tête, commissure des lèvres)
VRM : pas d'expression faciale pendant une action	Les expressions suivent uniquement l'état, l'action ne les déclenche pas	Ajouter mood + beats à côté de l'action, les mixer selon le poids de l'action (references/vrm.md §25)
L'action nécessite de fermer les yeux ou d'ouvrir la bouche, mais le modèle a « fatigué » / « sourire » qui bloque	overrideBlink / overrideMouth de l'expression est un bloc	Écraser ces expressions pendant l'action (§26)
VRM : clignement d'un seul œil invisible	blinkLeft/blinkRight non liés à une forme de morph	Remplacer par un plissement des deux yeux (§27)
VRM : une action interrompt une autre, le bras tombe puis se relève	La nouvelle action part de la pose debout, le crossfade passe par la pose debout	Démarrer la nouvelle action à partir du point le plus proche de l'état actuel + transition depuis le point d'interruption (§19)
VRM : doigts rigides ou poing fermé en capture de mouvement ; main toujours à moitié fermée dans les actions faites à la main	Redirection des doigts / l'action n'écrit pas les doigts	Enlever les doigts de la capture, écrire des formes de main dans l'action (§22, 23)
Main sur la joue, bouche, cœur : ne touche pas l'endroit visé si le modèle change	Seulement des angles	Calculer la cible en temps réel selon les os et le maillage, utiliser deux segments d'IK (§24)
Fin de danse : le pied revient brusquement en une frame	L'IK de jambe prend le relais dès la frame où le fondu commence	L'IK reprend progressivement selon le poids de l'action avec les jambes (§20)
Genou à moitié plié, trop de flexion en jambe détendue	Superposition de plusieurs décalages de bassin	Limite de genou, diviser par deux le décalage de bassin ; lever le talon augmente la flexion (§21)
VRM : yeux fixant la caméra en permanence	lookAt est réglé sur la caméra, les yeux tournent en sens inverse quand la tête tourne	Quand la tête tourne, le regard suit la tête, clignement en tournant la tête, micro-mouvements oculaires (§28)
Actions faites à la main saccadées, manque de fluidité	Chaque segment de clé a un ralentissement aux deux extrémités, chaque clé a une vitesse de 0	Spline cubique monotone + décalage des clés entre segments (§29)
Bras tendus qui balayent sur les côtés en s'étirant / bras levés horizontalement	Pas de segments pour le poing serré, l'avant-bras replié ; torsion et levée non séparées	Refaire en segments, torsion uniquement au niveau de l'épaule (§30)
Transfert de poids debout : tout le haut du corps penche d'un côté	La limite de genou réduit l'inclinaison du bassin, la taille et la poitrine compensent en sens inverse avec l'amplitude totale	Ajouter à la taille la partie d'inclinaison perdue par le bassin (§31)

Source et maintenance

• Source : Cirra (mascotte de bureau IA, RedCarpG/cirra-deskpet), octobre à novembre 2026.
  • Code Live2D : src/pet/live2d.ts, src/pet/live2d-physics.ts, src/pet/cubism-core.ts ; render engine untitled-pixi-live2d-engine 1.4.0 (PixiJS 8).
  • Code VRM : src/pet/vrm.ts, src/pet/vrm-motion.ts, depuis le 2026-11-11 aussi vrm-face.ts, vrm-hands.ts, vrm-blend.ts, vrm-reach.ts, vrm-gaze.ts ; commits 2b6ab57 (clampWhenFinished), e5e8687 (pas d'utilisation de combineSkeletons).
  • Documentation : 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.
  • Leçons : lessons/live2d-motion.md, lessons/threejs-vrm-animation.md (dépôt privé).
• Origine : Dossier skills/live2d-vrm-animation/ dans RedCarpG/redcarpg-skills. Le dossier ~/.claude/skills/ contient une copie installée, ne pas modifier directement. Le code de Cirra est la source, les deux ne sont pas automatiquement synchronisés.
• Comment modifier :
  • Modifier dans redcarpg-skills, via une PR ; incrémenter la version dans manifest.json, valider avec node scripts/validate.mjs, puis taguer (live2d-vrm-animation-v<version>), et réinstaller la copie locale. Vérifier d'abord les deux fichiers de leçons pour de nouvelles entrées à intégrer.
  • Après une mise à jour de three.js, three-vrm ou du moteur de rendu Live2D, revérifier les lignes du tableau « Pièges les plus fréquents » liées au comportement interne des librairies (mixer n'écrit pas les valeurs inchangées, clampWhenFinished, shouldRequestIdleMotion, ordre de chargement).
  • Pour un symptôme observé sur un seul modèle, préciser le type de modèle, ne pas l'écrire comme une règle générale.
• Historique des modifications :
  • 2026-11-12 · 1.0.0 : Intégration dans redcarpg-skills, publication publique. Chemins absolus locaux modifiés, projet source en lien ; contenu inchangé.
  • 2026-11-10 · Cirra · Première version : trois principes, tableau de dépannage rapide ; trois références (Live2D, VRM, génération IA) ; deux prompts de test dans evals/.
  • 2026-11-10 · Cirra · Modification de la §15 VRM (jupe qui traverse) : « remplacer par des capsules » ne fonctionnait pas, remplacé par enregistrement des collisions, capsules de jambe génériques, saut de bassin (docs/vrm-skirt.md) ; ajout d'une ligne au tableau.
  • 2026-11-10 · Cirra · §15 ajout : cheveux longs dans les manches (ne pas reculer les capsules de bras), vêtements qui ressortent = problème de skinning.
  • 2026-11-10 · Cirra · references/vrm.md ajout : « Os normalisés VRM 0.x face à -Z » (changer l'orientation dans la pose procédurale, ne pas annuler avec rotateVRM0 lors d'une rotation ; commit e2e6c0c, src/pet/vrm-basis.ts).
  • 2026-11-11 · Cirra · references/vrm.md ajout des §19–28 (interruption sans laisser tomber la main, reprise d'IK pour les jambes en fondu, limite de genou et talon, doigts de capture remplacés par formes de main, formes de main et poignet, main touchant le corps avec IK, action + expression, override bloque les battements, clignement d'un seul œil vide, yeux suivant la tête), §11 redirigée vers §25 ; ai-motion.md ajout du format et de la validation pour face, hands, reach ; tableau des pièges +9 lignes. Source : 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 fusionnés b2f115d, ea3be9e).
  • 2026-11-11 · Cirra · references/vrm.md ajout des §29–31 (ralentissement aux deux extrémités des clés → spline cubique monotone et décalage ; segmentation de l'étirement et torsion du bras ; limite de genou réduit l'inclinaison du bassin → haut du corps penché), tableau des pièges +3 lignes. Source : docs/vrm-motion-polish.md §12, smoothAt dans src/vrm-studio/motion-spec.ts, src/pet/vrm-pose.ts (commit fusionné c5b4728).
  • 2026-11-11 · Cirra · references/live2d.md §21 ajout : deux types d'exclusion pour les modèles VTube Studio (entrées physiques, paramètres faciaux sans Param), sinon les expressions faciales se retirent lors d'un hochement de tête. Source : standardInputs, isStandardParam dans src/pet/clash.ts, docs/expression-clash.md (commit 7721742).