RedCarpG/live2d-vrm-animation

Live2D / VRM キャラクターアニメーション

このスキルは、Live2D と VRM 両方のキャラクターに対応したデスクトップペット（末尾の「出典とメンテナンス」参照）に由来します。使用したモデルには、公式サンプル、VTube Studio 用モデル、VRChat から変換した VRM が含まれます。以下の手法はすべて試行・測定済みか、ユーザーが確認・修正したものです。

両方のキャラクタータイプに共通する3つの原則

1. プロシージャルレイヤーとモーションクリップは互いに上書きされます。 各フレームでどちらが先に計算され、どちらが後に書き込まれるかが、ユーザーの目に映るものを決定します。ほとんどの「ピカッと光る」「手が下がる」「頭が動かない」といった現象はここから発生します：
   • Live2D：プロシージャルな値は beforeModelUpdate 内に配置され、物理演算には入らず、髪や体は追従しません。physics.evaluate をラップし、物理演算の前に適用する必要があります。
   • VRM：three.js の AnimationMixer は、1フレーム内でブレンドされた値が前のフレームと同じ場合、ボーンに書き込みません。毎フレームプロシージャルに設定された立ち姿勢や呼吸は、クリップが「停止」している部分から漏れ出します。再生中のクリップが書き込んでいるボーン（clip.tracks のノード名による）をスキップする必要があります。一時停止時も同様で、プロシージャルな立ち姿勢の再書き込みを停止する必要があります。
2. モーションファイルを変更せず、後ろにプロシージャルレイヤーを追加します。 手作業のキーフレームや AI が生成したモーションは、多くの場合、数本のボーン（手を振るなら腕だけ）しか動かさず、操り人形のようになります。クリップの後にプロシージャルに計算された「連動」（肩がついて上がる、体幹が譲る、手首が遅れる、頭が半拍遅れる）を追加しますが、クリップ自身が書き込んでいるボーンには重ねません。一度設定すれば、すべてのモーションで効果が得られ、オン/オフの比較も可能です。
3. 検証はフレーム単位の記録に依存し、目視確認には頼りません。 アニメーションの問題は1～2フレームしか続かないことが多く、肉眼で修正を確認するのは非常に困難です。問題のボーン（パラメータ）が描画された時点（Live2D の beforeModelUpdate 内、またはレンダリング後 VRM で値を読み取る）の値をフレームごとに記録し、修正前と修正後で比較します。さらに、異なる2つのモデルでスクリーンショットを撮って確認します。

いつどこを読むか

やりたいこと	読む場所
Live2D：読み込み、パラメータ書き込み、物理演算、待機モーション、アクション、固定、表情	references/live2d.md
VRM：プロシージャルポーズとクリップ、連動レイヤー、モーションキャプチャクリップ、表情、スプリングボーン、透明ウィンドウ	references/vrm.md
VRM：モーションと表情の組み合わせ、手の形と手首、手を体に当てる IK、中断時に手が落ちない、脚の限界、目と頭の追従、キーフレーム補間と区分化	references/vrm.md 第19～31条
AI による表情やモーションの生成・修正	references/ai-motion.md
音楽に合わせてうなずく、話すときに頭が動く	references/live2d.md 第16条、references/vrm.md「ビート追従」

最も一般的な落とし穴（最初にこれらを確認すること）

現象	原因	修正方法
Live2D で「Could not find Cubism runtime」エラーまたは描画されない	読み込み順序の誤り	Cubism Core → レンダーパイプラインを登録するモジュール → PixiJS Application.init() → モデル
Live2D のパラメータ読み出し値が58、null などの異常値	文字列 ID を直接渡している	まず internalModel.getIdSafe(name) でハンドルに変換する
Live2D で頭が追従しない（VTube Studio モデル）	ParamAngle* が物理演算の出力であり、書き込まれると上書きされる	physics3.json を読み込み、その入力パラメータに書き換える
Live2D で頭だけ揺れ、髪や体が動かない	プロシージャルレイヤーが物理演算の後に適用されている	physics.evaluate をラップし、その前に追加する
Live2D で立ち尽くして動かない	VTube Studio モデルに適切な Idle がない	プロシージャル待機モーション：頭、体の3つの低速サイン波 + 呼吸、標準パラメータのみ書き込む
Live2D で stopAllMotions 後に再び動き出す	エンジンがモーションがないと判断し、Idle を再再生する	motionManager.groups.idle を存在しないグループに変更し、breath も停止する
VRM 手作業キーフレームモーション停止中に手が下がり、開始/終了時にピカッと光る	mixer が変わっていない値を書き込まず、プロシージャルな立ち姿勢が露出する	プロシージャルポーズがクリップの書き込んでいるボーンをスキップする
VRM 1回限りのモーション終了時に1フレームで元の姿勢に戻る	clampWhenFinished=false の場合、mixer が finished イベントの前にアクションを終了する	clampWhenFinished = true に設定し、さらに fadeOut する
VRM モーションキャプチャモーションで立位が広く、開始時にずれ、スカートが舞い上がる	クリップに股関節と脚のトラックが含まれている	変換時に股関節と脚のトラックを削除し、上半身のみを使用する
VRM スカートが太ももにめり込む、衝突補助線に球が1～2個しか表示されない	コライダーがスプリングチェーンの衝突グループに登録されていない（three-vrm は登録済みのものだけを認識する）	標準的なボーンに従い、股関節下のチェーンに脚用のカプセルを追加する；股関節が1フレームでジャンプしないようにする（references/vrm.md 第15条）
VRM クリップに書かれた表情が見えない	毎フレームのステート表情、まばたき、リップシンクが上書きする	クリップはボーンのみ書き込む
小さいサイズで表情が見えない	表情ファイルがごく一部しか変更していない	各感情にさらにパラメータレイヤーを重ねる（目を細める、頬を赤らめる、首をかしげる、口角を上げる）
VRM モーション中に顔に表情がない	表情がステートのみに追従し、モーションに付随していない	モーションに mood + beats を記述し、モーションの重みに応じてブレンドする（references/vrm.md 第25条）
モーションで目を閉じたり口を開けたいが、モデル自身の「眠い」「笑う」が妨げる	表情の overrideBlink / overrideMouth がブロックとなる	その瞬間にこれらの表情を抑制する（第26条）
VRM 片目まばたきが見えない	blinkLeft/blinkRight がブレンドシェイプにバインドされていない	両目を一緒に細めて代用する（第27条）
VRM あるモーションが別のモーションを中断すると、手が落ちてから再び上がる	新しいモーションが立ち姿勢から始まり、クロスフェードが立ち姿勢を経由する	新しいモーションの中で現在の姿勢に最も近い時点から開始 + 中断した時点から遷移する（第19条）
VRM モーションキャプチャで指が板のように伸びきる、または握り拳になる；手作業キーフレームモーションで指が常に半握り	リターゲットされた指 / モーションが指を書き込まない	モーションキャプチャの指を除去し、モーションに手の形を書き込む（第22、23条）
頬杖、口を覆う、ハートを作るなどの動作が、体型が変わると位置が合わない	角度のみ書き込んでいる	ボーンとメッシュからリアルタイムに目標を計算し、2段階 IK を使用する（第24条）
ダンス終了時に脚が1フレームで戻る	脚 IK がフェードアウト開始時に即座に制御を引き継ぐ	IK が脚を含むモーションの重みに徐々に追従するようにする（第20条）
膝が半屈み、リラックスした脚の曲がりが大きすぎる	複数の股関節オフセットが重なっている	膝の上限を設定し、股関節の縮小を半分に；かかとを上げるとむしろ曲がりが大きくなる（第21条）
VRM の目が常にカメラを凝視している	lookAt がカメラを向いており、頭を回すと目が逆方向に動く	モーションで頭を回すときに視線を頭に追従させる、頭を回すときにまばたきをする、マイクロサッケード（第28条）
手作業キーフレームモーションがカクカクして滑らかでない	各キーフレーム区間の両端が遅く、各キーフレームの速度が0	単調3次スプライン + 各キーフレームをずらす（第29条）
伸びをしたり手を挙げると、腕が真っすぐ横から弧を描いて上がる / 横に水平に伸びる	拳を握る、前腕を折りたたむなどの区間がない；捻りと挙上が分離されていない	区間に分割して再作成し、捻りはドアフレームの瞬間のみ行う（第30条）
重心移動時に上半身全体が片側に傾く	膝の上限が股関節の傾きを縮小したが、腰と胸は完全な反対方向の回転を続ける	股関節が縮小した傾きの一部を腰に追加する（第31条）

出典とメンテナンス

• 出典： Cirra（AI デスクトップペット、RedCarpG/cirra-deskpet）、2026年10月～2026年11月。
  • Live2D コード：src/pet/live2d.ts、src/pet/live2d-physics.ts、src/pet/cubism-core.ts；レンダリングライブラリ untitled-pixi-live2d-engine 1.4.0（PixiJS 8）。
  • VRM コード：src/pet/vrm.ts、src/pet/vrm-motion.ts、2026年11月11日以降 vrm-face.ts、vrm-hands.ts、vrm-blend.ts、vrm-reach.ts、vrm-gaze.ts；コミット 2b6ab57（clampWhenFinished）、e5e8687（combineSkeletons 不使用）。
  • ドキュメント：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。
  • 経験：プライベートリポジトリの lessons/live2d-motion.md、lessons/threejs-vrm-animation.md。
• ソース： RedCarpG/redcarpg-skills の skills/live2d-vrm-animation/。~/.claude/skills/ にあるのはインストールされたコピーなので、直接編集しないでください。Cirra のコードがそのソースであり、両者は自動的に同期されません。
• 変更方法：
  • redcarpg-skills で変更し、PR を作成します；manifest.json のバージョンを上げ、node scripts/validate.mjs が成功したらリリース（タグ live2d-vrm-animation-v<バージョン>）し、その後ローカルコピーを再インストールします。まず上記の2つの lessons ファイルに含めるべき新しい項目がないか確認してください。
  • three.js、three-vrm、Live2D レンダリングライブラリがアップグレードされた後は、「最も一般的な落とし穴」の表の中でライブラリ内部の動作に関連するいくつかの項目（mixer が変わっていない値を書き込まない、clampWhenFinished、shouldRequestIdleMotion、読み込み順序）を再確認する必要があります。
  • 1つのモデルでのみ確認された現象については、どのタイプのモデルかを明記し、一般的なルールとして記述しないでください。
• 更新履歴：
  • 2026-11-12 · 1.0.0、redcarpg-skills に移行し公開。ローカルの絶対パスを修正し、ソースプロジェクトへのリンクに変更；内容は変更なし。
  • 2026-11-10 · Cirra · 初版：3つの原則、問題点早見表；Live2D、VRM、AI 生成モーションの3つのリファレンス；evals/ 内の2つのテストプロンプト。
  • 2026-11-10 · Cirra · VRM 第15条（スカート貫通）を修正：以前の「カプセルに変更すれば解決」は効果がなく、衝突グループ登録、汎用脚カプセル、股関節ジャンプの3項目に変更（docs/vrm-skirt.md）；問題点早見表に行を追加。
  • 2026-11-10 · Cirra · 第15条に長い髪が袖に入る（腕カプセルは収縮できない）と、衣服が突き出るのはスキニングの問題であることを追加。
  • 2026-11-10 · Cirra · references/vrm.md に「VRM 0.x の正規化されたボーンは -Z 方向を向く」（プロシージャルポーズの向き変更、回転時に rotateVRM0 をキャンセルしない；コミット e2e6c0c、src/pet/vrm-basis.ts）。
  • 2026-11-11 · Cirra · references/vrm.md に第19～28条を追加（中断時に手が落ちない、脚を含むクリップのフェードアウト時 IK 制御、膝の上限とつま先立ち、モーションキャプチャ指の手の形への置き換え、手の形と手首、手を体に当てる IK、モーションと表情の組み合わせ、override がビートをブロック、空の片目まばたき、目と頭の追従）、第11条を第25条への参照に変更；ai-motion.md に face、hands、reach の形式と検証を追加；問題点早見表に9行追加。出典：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（マージコミット b2f115d、ea3be9e）。
  • 2026-11-11 · Cirra · references/vrm.md に第29～31条を追加（キーフレーム区間の両端が遅い → 単調3次スプラインとキーフレームのずらし；伸びの区分と上腕の捻り；膝の上限による股関節の傾き縮小 → 上半身が傾く）、問題点早見表に3行追加。出典：docs/vrm-motion-polish.md §12、src/vrm-studio/motion-spec.ts の smoothAt、src/pet/vrm-pose.ts（マージコミット c5b4728）。
  • 2026-11-11 · Cirra · references/live2d.md 第21条に VTube Studio モデルの2つの除外タイプ（物理入力、Param なしの顔パラメータ）を追加。これにより、顔の表情がうなずきと競合しなくなる。出典：src/pet/clash.ts の standardInputs、isStandardParam、docs/expression-clash.md（コミット 7721742）。