MMD pose and motion

MMDの制作を、意図を読めるポーズと時間的な動きとして仕上げる。ツールが成功しても、自然な姿勢や狙った表情を確認したことにはならない。

最初に確認すること

• 制作・実機確認では mmd_list_windows、mmd_get_ui_state、キャプチャから対象のHWND・モデル・フレームを特定する。複数起動時に別の作業ウィンドウを流用しない。
• 制作依頼で許可された範囲はそのまま進め、現在のMMDウィンドウを基本に使う。別起動はシーンを置き換える検証など必要性がある場合に絞り、理由を説明する。未保存のシーンや未登録のポーズを失う可能性がある操作は、既に具体的な許可がない限り先にユーザーへ確認する。現行MCPでは未保存状態を完全には判定できないため、必要なら質問し、「未保存ではない」と推測しない。名前を付けて保存すると作業中の保存先も変わるため、無断でバックアップ代わりに使わない。
• 制作用のMMDをMCPクライアント（Codex・Claude Code 等）から新規起動する場合は python -m mmd_mcp.launcher "C:/MMD/MikuMikuDance.exe" を使う（Pythonはmmd-mcp導入環境のもの）。ローカルWMI経由で一時停止状態のプロセスを作り、Windowsジョブに属さないことを確認してから実行する。戻ったPIDを mmd_list_windows のPIDと照合してHWNDを取得する。window_ready=false はまだウィンドウ確認前という意味。通常の subprocess.Popen、Start-Process、コンソール分離だけの起動では起動元のMCPクライアント終了時に巻き込まれる可能性がある。専用起動が失敗したら通常起動へ戻さず、手動起動を案内する。使い捨て検証用プロセスの起動・終了は別扱い。
• モデルの同梱説明を読む。文字化けはBOMとエンコーディングを確認する。Tda V4XでAutoLuminousを使わない場合は、作者の説明どおり「AL未使用」を1にする。
• 基本動作の検証モデルはユーザー指定の Tda式初音ミクV4X Ver1.00 を優先する。別のモデル指定は尊重する。手指のテストでは袖・髪で手が隠れないモデル／画角を選ぶ。あにまさ式ミクの長袖では指と袖の干渉を切り分けにくい。

骨格・軸・動きの違いを調べる

調査依頼では、まず mmd_get_model_profile(model_path=絶対パス, bone_name="右手首") を使う。MMDを起動・選択・フレーム移動せずにPMD/PMXを読む。日本語名またはPMXの英語名が重複する場合は bone_index を使い、名前とインデックスは同時指定しない。モデルのファイルが不明なら確認し、画面のモデル名からパスを推測しない。

investigation.target.ancestor_chain は対象→ルート順。手捩・腕捩・上半身2などの中間親、related_dependencies の付与元・割合・IKリンク／制限を比較する。common_bone_presence は名前のチェックリストで、標準準拠や互換性の証明ではない。PMDの kind・tail_raw・ik_index_raw は種類依存の生値。PMXへ変換した値や名前から補った膝の制限を、ファイルの宣言として扱わない。

PMXの fixed_axis と local_axes は操作の軸制限・ローカルフレームで、VMD回転の基底変換を指示するものではない。宣言がないことから「軸が同じ」「動作不良の原因」と断定しない。画面のギズモ、UI角度欄、VMD四元数を区別する。既存の rotation.from_ui をPMXローカル軸で無条件に挟み込む変換はしない。

derived_hand_geometry は手首・人指１・小指１の初期位置から算出した方向候補。掌の表裏・現在の姿勢・カメラ方向は確定しない。縮退なら法線はnull。報告ではファイルの宣言、計算からの候補、未確認の実機挙動を分ける。親循環や軸の縮退の警告があれば先に示す。ボーン／IKより後のモーフ・物理はこの解析の対象外。

数値や軸の実機較正が必要なら、調査結果をもとに対象・単軸の小さな変更・比較画角を決める。調査だけの依頼からキー変更へ進めない。標準名が一致していても、親構成・休止位置・付与・現在の親姿勢の違いを確認する。

ポーズを作る

感情と主要動作を先に決め、全身の重心、上体、肩、肘、手首、指、顔の順に整える。全身の支えと手のシルエットを別々に確認する。左右対称の同じ数値や一律の軸方向を別モデルへ流用しない。

mmd_get_model_profile でファイルの対応状況と初期ボーン位置を確認する。意味ベースの操作はファイルハッシュを限定した対応モデル用。未対応モデルで対応したと主張せず、名前を確認して直接ボーン操作を使う。UIからロード元ファイルのハッシュは証明できず、ライブ照合はボーン名と順序によることに注意する。

mmd_compile_pose は骨格に合った絶対値のキー候補を返すだけ。実機への適用・細部の修正・表情設定は、1件でも mmd_batch_bone_keys を使う。items の各項目に frame と pose／bones／morphs を指定する。意味ポーズにはトップレベルの model_path が必要。明示したボーンの軸値は意味ポーズを上書きする。キー登録は項目ごとの register_key（既定true）で制御する。登録せず試す場合はfalseにし、対象フレームに留めるなら return_to_frame=false を指定する。バッチは開始時にも対象フレームを再評価するため、先行する未登録編集の保持を前提にせず、必要な変更を同じ項目へまとめる。直接操作とVPD/VMD読み込み・保存は別操作。

手首のひねりは前腕の方向を基準にする。Tda V4Xでは手捩りボーンを使い、上半身2や親指0を含む構成を尊重する。ピースは人差し指・中指の開きだけでなく、薬指・小指・親指の折り込みと手のひらの向きが見える角度で確認する。

正面と斜めから確認し、関節のねじれ、腕と胴体／髪の重なり、足の接地、袖へのめり込みを修正する。足IKを動かすだけで重心移動が完成したと判断しない。

笑顔の「笑い」や細目など、目を細めるモーフに「まばたき」を重ねると、変形が加算されて目が閉じすぎるケースがよくある（ユーザーから共有された制作上の知見）。表情とまばたきを別々に仕上げず、同時に効く状態でまぶたの形を確認する。必要に応じてまばたきを弱める／省く、または目を細めるモーフを一時的に弱めて閉眼へつなぐ。適切な組み合わせと強度はモデルごとに調整し、閉じ切る瞬間だけでなく前後の補間中も確認する。

モーションを作る・直す

モーションの設計・評価では references/motion-principles.md を読む。作品に依存しない支持・接地、階段打ち、慣性、補間、手指、表情、ループの判断基準をまとめている。新しいモーションの編集経路は references/authoring.md を読む。

Tda V4Xで右手の手振りを新規制作する場合は、references/wave-recipes.md のモデル限定レシピを優先する。控えめ／大きめ、1〜3往復、3種類の速さを扱い、生成用Pythonと数値検査を同梱する。固定した全身を含む独立クリップなので、既存の演技への腕だけのパッチとして読み込まない。対応範囲外は別に検証する。

回転・踏み替え・ダンスのループを扱う場合は、references/rotation-steps.md の支持足、回転方向、疎なキーの継ぎ目、骨格の制約の確認方法を参照する。元モーションの流し込みと、独立した自作モーションの検証を区別する。

跳躍、着地後の慣性、短い喜びの芝居を扱う場合は、references/inertia-jumps.md を読む。Tda限定の小ジャンプ／喜び跳びの独立レシピと適用条件を扱う。汎用の演技設計と固定した生成条件を区別する。「可愛い」の狙いが異なる場合は、レシピへ押し込めず主動作から設計する。

意図が読める主要ポーズを少数のキーで作り、予備動作、主動作、行き過ぎ、落ち着き、保持を必要に応じて配置する。胴体・腕・頭・指・表情を毎回同時に開始／停止させない。数フレームずらす場合も、効果を連続画像で判断し、固定の比率を万能ルールにしない。

階段打ちは、連なる部位のキーを時間方向に少しずつずらし、動きが順に伝わるようにする基本技法。例えば腕を振るときは肩・腕→肘→手首→指、お辞儀なら上半身→上半身2→首→頭という順序を候補にする。動き出しだけでなく、折り返し・止まり際の追従も見る。ずらす量や順序を固定レシピにせず、動作の速さ・重さ・狙う表情に合わせて調整する。視線を安定させたい頭や接地中の足まで一律に遅らせない。

補間曲線は、キー間でどのように変化が進むか、つまり速さと緩急を決める。緩やかに動き出して中間で速くなり、終わりで減速するS字を基本とし、等速で動かしたい区間には直線を使う。通常の挨拶や芝居では共通のS字から始めてよい。全ての部位に別の曲線が必要なわけではなく、動きを見て必要な区間の加速・減速を調整する。

階段打ちは部位間のタイミング、補間曲線は各区間の速度変化として組み合わせる。通過するだけの中間キーまで毎回停止型のS字にすると、途中で不必要に減速するため、前後の速度がつながる曲線やキー配置にする。MMDのボーン補間は移動X/Y/Zと回転で別設定であり、設定はそのキーに到着する区間に効く。UIで補間を手動調整する場合は「自動設定」をOFFにして意図しない再設定を避け、変更後の曲線を確認する。VMD経由でも、適用・書き出し後に mmd_inspect_vmd で保持された補間を照合する。

回転はQuaternion補間となるため、曲線を変えても腕の通る経路が解決しなければ中間ポーズを足す。指を開く瞬間と笑顔が出る瞬間も主動作に合わせて編集する。参考: MMD swampの 階段打ち と 補間曲線の設定。

mmd_preview_motion の動画とコマ一覧を使い、キーの間、動作の前後、保持中も確認する。これはフレーム評価によるサンプルで、リアルタイム再生や物理のベイクではない。髪・衣装などの物理依存部分は、その区別を示して別途確認する。ヒーロー画像一枚をモーション全体の検証証拠にしない。

比較は同じモデル、カメラ、区間、サンプル間隔で行う。変更前と変更後を保存し、指の読みやすさ、重心、タイミング、引っ掛かり、干渉のどこが改善したかを具体的なフレームで説明する。

アクセサリ

mmd_select_model(selector_index=0) の後に、mmd_batch_accessories の path でXファイルを読み込み、配置・登録までまとめる。読み込みだけなら mmd_load_file(kind="accessory") も使える。mmd_list_accessories と mmd_select_accessory で対象を明示する。

mmd_get_accessory で位置・回転・サイズ・透明度・表示・影・親を読む。書き込みは1個でも複数でも mmd_batch_accessories。各項目は path（新規読み込み）か selector_index（既存）と、フレームごとの keys。親は parent_model_index / parent_bone_name をキーに入れる。親の変更はワールド位置を保持しないため、親を決めてからローカル位置と回転を整える。削除は mmd_delete_accessories。

登録はキーの register_key（既定true）で同時に行う。保存は mmd_save_project。位置が変わったこと、フレームを移動して登録値へ戻ることを確認する。アクセサリキーはVMDの編集用ボーンキーとは別で、PMMに保存する。

ボーン操作モードとスクショ

MMDのボーン操作パネルのモード（実測 2026-09-07）: 選択=0、BOX選択=1、回転=3、移動=4。2は捩ボーン（軸固定）をマウスでつかんで回した後に観測した値で、捩ボーン専用の軸回転状態と見ている（ユーザー伝聞・未検証。ネイティブ経由で捩ボーンを選んだだけでは0のまま）。ネイティブ選択DLLは0／3／4だけ受け付け、それ以外では status=-4 で拒否する。mmd_select_bone と mmd_batch_bone_keys は開始時にモードを読み、対象外なら自分で「選択」ボタン（ID 490）を押して戻し、結果の operation_mode_switched_from に元の値を返す。人がギズモで直した直後でも止まらない。

ボーンを選択している間はボーン表示が画面に出るので、確認用のスクショには不向き。mmd_select_model(selector_index=0) でカメラ・照明・アクセサリモードに切り替えるとボーン表示が消える（実機確認 2026-09-07）。撮ったら mmd_select_model でモデルに戻す。

目標指定を使う: ArmPose の hand_at（ear／shoulder／chest／overhead）と palm_facing（camera／up／down）を書くと、コンパイル時にそのモデルの順運動学で arm_lift／elbow_bend／wrist_turn が解かれ、数値の当てずっぽうを避けられる。コンパイル結果の fk.right_arm、バッチ結果の frames_completed[].fk.summary.right_arm などに手首位置（頭ボーン比）・掌法線・palm_camera_dot が入るので、キーを打つ前にそこを見る。手振りに wrist_tilt 単独を万能に使わない。この値は固定軸の候補であり、狙う往復方向を骨格調査と実機で確認する。現行FKは限定した腕チェーンを評価し、全身・付与・物理を網羅しない。palm_facing="camera" も現在のカメラを取得せず固定の正面方向を仮定するため、実カメラへの正対の証拠にはしない。

ポーズの検算は順運動学で先にやる。休止位置は mmd_get_model_profile の rest_position、角度→四元数は rotation.from_ui。Tdaの右腕はAポーズで水平から37.5°下がっているため、arm_lift 58＋elbow_bend 85 で手は頭頂に届く（耳の高さは arm_lift 35＋elbow_bend 115）。手のひらをカメラへ向ける前腕のひねりは腕の構えに依存し、定数ではない（今日の実測: 意図した構えで90°、実際の構えでは人の目で105.6°）。

カメラ・モデル設定・MME

音・カメラ・表情・舞台を組み合わせるときは references/visual-direction-principles.md を読む。カットの役割、画角と距離、表情との接続、舞台配置、エフェクトの役割と検証を扱う。

カメラ・ライトはモデル選択0で mmd_batch_camera_keys にフレーム別の camera／light／shadow／gravity を渡す。モデルの表示・セルフ影・加算・IK ON/OFF・外部親は、対象モデルを選んで mmd_batch_model_flags を使う。どちらも各項目の register_key は既定true。

MMEは現在の割当をEMMへ出力し、mmd_read_effect_assignments の objects と effect_sections で対象を確認する。EMMのIDはUI選択インデックスとは別。mmd_write_effect_assignments の sections でMain・環境光・材質・影等をまとめて編集する。材質IDは Pmd3[173] 形式、表示切替は visibility、元ファイルを保持するなら新規 output_path を指定する。Owner・既存の別セクションは保持される。これはファイル編集で、画面への反映ではない。MMEの割当ダイアログ内「ファイル → 設定を読込」ならPMM再読み込みを伴わず反映できる。mmd_transfer_effect_assignments の operation="export" / "import" で実行し、再エクスポートしたEMMで変更内容を照合する。PMM再読み込みはシーンを置き換える。EMM編集後に先にPMM保存すると割当が上書きされることがある。エフェクト用アクセサリの数値はアクセサリバッチで設定する。

ネイティブ編集と出力

既存のキーを扱うときは mmd_get_timeline_context の実際のトラック名で範囲選択し、mmd_edit_actions でコピー・貼付・削除を行う。undo / redo はMMDが利用可能なボーン編集等に限り、カメラやモデル削除の復旧には使えない。

キーを選んで mmd_export_file(kind="motion") で保存し、mmd_inspect_vmd で結果を検査する。既存ボーン／カメラの補間は mmd_edit_vmd で新規ファイルへ編集できる。VMD読込はマージなので、時刻移動・削除を反映するときは対象の古いキーを先に整理し、0フレームで読み込む。PMMの重力・アクセサリ・外部親をVMDだけで保存できたと判断しない。

表示・物理・MMEの切替は mmd_set_scene_settings の明示値を使う。アクセサリ加算は mmd_batch_accessories の項目レベル additive で、キーにはしない。描画順を変えたらモデル番号と親選択欄を取得し直す。

完成画像は mmd_export_file(kind="image")、動画は出力サイズを設定して mmd_export_video。rendering なら同じサーバーで mmd_get_video_export_status を確認し、完了まで編集しない。mmd_preview_motion はUIを含む確認用で、ネイティブの本番画像・AVI出力と区別する。

修正から改善する

ユーザーがお手本を作った、同じ不自然さが再発した、改善を依頼されたときは references/improvement-loop.md を読み、観測→仮説→小さな修正→同条件の比較→採用／棄却を進める。調査だけの依頼では差分と候補までに留める。指の制作では references/hand-calibration.md のモデル限定の校正データを必要に応じて参照する。

終了時

編集・キー登録・保存は別々の操作。フレーム移動で未登録のポーズが失われるため、残す内容を先に登録または編集データへ保持する。タイムアウトや部分失敗時には、返された完了箇所と現在の実機状態を見て再開し、無条件に再実行しない。

成果物はPMM、必要なVMDと編集用JSON、見やすいキャプチャ／短いプレビュー。モデル本体・テクスチャを配布物に含めない。今回できた範囲と未検証の範囲を区別して伝える。