Blender Live Rigging は何をしますか?
ユーザーが開いているBlenderインスタンスを直接操作します。ヘッドレスバッチ処理やアプリの終了は行いません。「完了」と主張するたびに、評価済みデプスグラフから読み取った数値で裏付ける必要があります。レンダリングはデフォルトでオフであり、オーナーが依頼した場合にのみ行われます。
リポジトリドキュメント(毎回読む必要はなく、深い情報が必要なときに参照):
docs/MCP_BRIDGE.md— プロトコル、起動モード、落とし穴、ビューポートフォーカスdocs/RIGGING_PLAYBOOK.md— 完全なリギング手法とエクスポート/復元レシピdocs/VERIFICATION.md— メトリクスしきい値とスニペットdocs/RENDERING.md— オーナー要求レンダーパスreference/roblox-avatar.md— R15ボディコントラクト、その場歩行IK、FBX検証reference/blender-5x-api.md— スロット化アクション、測定済み5.4 API、glTF時間原点reference/glb-qa.md— レンダリング不要GLBゲート、ベースライン、ネガティブテスト証拠docs/CASE_STUDY_KNIGHT.md— 測定済みR15アバター + ウォークループ(リポジトリルート)
このスキルが andypratama3/blender-mcp からインストールされた場合、リポジトリルートはこのファイルから3階層上になります(skills/blender-live-rigging/SKILL.md)。
ハードルール
- ライブGUIのみ。
bpy.app.background == Falseを確認。ユーザーが作業中にBlenderを強制終了しないでください。ポート競合のために再起動が必要な場合は、先に.blendを保存し、同じファイルを開き直してください。 - オーナーが依頼しない限りレンダリングしない。 デフォルトの検証は数値ベース:頂点座標、幅、面積、比率。オーナーが明示的にレンダリングを要求した場合のみ、ライブセッションで行います(レンダリングは依頼時のみ参照)。
- 編集対象にビューポートをフォーカスする。 変更前後で、オブジェクト/ボーンを選択し、1つをアクティブにし、
view3d.view_axis+view3d.view_selectedを実行。アセット平面に合った軸を選択(フラットなXZアセットにはFRONT)。 - 評価メッシュを使用し、オリジナルは決して使用しない:
obj.evaluated_get(depsgraph).to_mesh()。 scene.frame_set(f)でドライバー評価を強制する —view_layer.update()だけでは不十分。bpy.ops.wm.save_as_mainfile(filepath=..., compress=True)でインクリメンタルに保存。マイルストーンごとに実行し、成果物はプロジェクトフォルダ内に保持。- 1回の
executeは1つのアトミックでべき等なステップとし、それを証明するメトリクスを返す。 - 床に触れる部分はメッシュで測定し、ボーンでは測定しない。 ボーンテールは靴底より0.4スタッド上に位置することがあるため、ボーンテールのゲートパスが通ってもブーツが地面にめり込む可能性があります。評価メッシュの最も低いワールド頂点を使用してください。
1. 接続
ブリッジは公式アドオン bl_ext.blenderlab.mcp を使用し、127.0.0.1:9876 で動作します。
lsof -nP -iTCP:9876 -sTCP:LISTEN # 起動前に空いていることを確認
open -a Blender --args --online-mode "/abs/path/file.blend" # macOS
sleep 8 && lsof -nP -iTCP:9876 -sTCP:LISTEN
--online-mode は必須です(自動起動には bpy.app.online_access が必要)。また、--factory-startup は絶対に使用しないでください(拡張機能が無効になります)。その後:
python3 scripts/blender_mcp.py 'import bpy
result = {"gui": not bpy.app.background, "file": bpy.data.filepath}'
2. アセットの検査
glTFをインポートし、matrix_world をメッシュデータにベイクし、空の親を削除し、重複を結合(remove_doubles(1e-5))、連結シェルをカウントし、ASCIIシルエットを表示して平面、ピボット、可動部品を特定:
blender -b --factory-startup --python scripts/inspect_glb.py -- "/path/asset.glb"
3. リグトポロジーの決定
メカニカルアセットの場合: 剛体パーツ、剛体ウェイト、パーツごとに1ボーン。ハサミ/プライヤー形状の場合、パーツを対角線上にペアリング(左ハンドル+右ジョー半分)し、ハンドルとジョーが一緒に開くようにします。中央線で分割すると、ハンドルが開くにつれてジョーが閉じます。
ヒンジピボットをハンドルの接合部に配置し、シームカットもそこに配置します。ボーンの rotation_euler.x がワールドヒンジ軸と正確に一致するように調整:
d = (Vector(b.tail) - Vector(b.head)).normalized()
b.align_roll(Vector((d.z, 0.0, -d.x))) # ローカルX == ワールドY
4. メッシュの準備
剛体パーツの境界ごとに use_fill=True でバイセクトし、キャップを約0.0004オフセットしてZファイティングを防止。キャップ面のみ反転(glTFカスタム分割法線を維持)。結合前にパーツごとに頂点グループを割り当て、その後 ARMATURE モディファイアでペアレント化。
5. コントロールとアニメーション
1つのカスタムプロパティ(open、0~1)が、シンプルなドライバー式を通じてすべてのボーンを駆動し、安全性のために LIMIT_ROTATION を追加。rotation_euler を駆動する前に rotation_mode = "XYZ" を設定。ループアクションのためにプロパティ(ボーンではなく)にキーフレームを打ち、BEZIER + AUTO_CLAMPED を設定。
6. 検証(成功を主張する前にゲートを通過)
| メトリクス | しきい値 |
|---|---|
| ソースメッシュとの静止偏差 | < 1e-5 |
| ループシーム(最終フレームと最初のフレームの差) | 0 |
| 開閉時の面面積比率 | 0.99–1.01 |
| ハンドルとジョーが両方とも外側に動く | > 0 |
| ウェイトが割り当てられた頂点 | 100% |
| 非多様体 / 面積ゼロの面 | 0 |
| 最も低い変形頂点と床の差 | ≥ −0.006、スタンスフット 0 ± 0.006 |
scripts/verify_rig_glb.py は、エクスポートされたGLBを別のBlenderプロセスに再インポートし(ライブセッションを妨害しない)、ノード/スキン/アニメーションのカウントとフレーム1/15/30/60での幅を出力します。
移動アニメーションの場合、手動でジョイント角度をキーフレームする代わりに、足首ターゲットに対する2ボーンIKで脚を解決し、すべてのフレームで測定:
low = min((ev.matrix_world @ v.co).z for v in ev.to_mesh().vertices) # フレームごと
ボーンゲートとメッシュゲートが一致しない場合、メッシュゲートが正しいです。
6d. レンダリング不要GLB QA
python3 scripts/glb_qa.py export/model.glb --loop --max-tris 20000
python3 scripts/glb_qa.py export/tool.glb --manifold
標準ライブラリのみ、Blender不要:GLBコンテナを直接読み取り、ヘッダー長、アクセッサ境界、ウェイト総和、未ウェイト頂点、ジョイントインデックス、バインドポーズカウント、キーフレーム順序、クォータニオンノルム、ループクロージャー、NaN、および(--manifold の場合)境界エッジをゲートします。失敗した場合は終了コード1。verify_rig_glb.py は可動部品の幅測定を担当します。ゲート、ベースライン、およびそれらが捕捉した5つの意図的に破損したファイル: reference/glb-qa.md。
6b. マルチファイルプロジェクトスクリプトをライブ実行
自身のモジュールをインポートするスクリプトは、ライブセッション内でパスによってロードする必要があります:
import importlib.util, sys
spec = importlib.util.spec_from_file_location("walk_cycle", "/abs/project/walk_cycle.py")
mod = importlib.util.module_from_spec(spec)
sys.modules["walk_cycle"] = mod # そうしないとdataclass/インポートが重複と見なす
spec.loader.exec_module(mod)
result = mod.main(save=True) # 測定されたゲートの辞書を返す
__main__ はヘッドレス実行用に残し(blender -b file.blend --python walk_cycle.py -- --save)、ブリッジからは main() を呼び出すことで、1つのスクリプトが両方のパスに対応します。
6c. Blender 5.x でのアクション(スロット化)
Action.fcurves、Action.groups、Action.id_root は5.4には存在しません。チャンネルバッグウォークを再入力する代わりにヘルパーを使用し、スロットを明示的にバインドします:
# ライブセッション(cwd = このスキルフォルダ); 結果を `result` として返す
python3 scripts/blender_mcp.py "import sys; sys.path.insert(0, 'scripts')
import action_compat
result = action_compat.audit()"
# ヘッドレス; スロットがバインドされていない場合は終了コード1
blender -b file.blend --python scripts/action_compat.py
from action_compat import iter_fcurves, ensure_fcurve, assign_action
slot = assign_action(obj, action) # 代入だけでは action_slot が None のまま
ensure_fcurve(action, slot, 'pose.bones["Head"].rotation_euler', 1, group_name="HeadTwist")
測定された障害モード: すでにスロットを持つアクションを異なるIDに割り当てると、animation_data.action_slot is None のままになり、リグはエラーなしで静止状態になります(アニメーションされた 3.92 ではなく頭が 4.0 の位置)。ゲート: action_compat.py が、すべてのアニメーションオブジェクトについて slot_assigned: true かつ slot_fcurves > 0 を報告する。また、channelbag.fcurves.new(..., group_name=...) を使用し、action_group= は使用しない。
詳細と残りの測定API: reference/blender-5x-api.md。
7. glTFのエクスポート
glTFにはドライバー、カスタムプロパティ、コンストレイントがありません。これらをベイクします:
- ソースアクションの名前を変更(
*_src)し、ベイクされたアクションにクリーンな名前を付けます。 - カスタムシェイプウィジェットオブジェクトをリンク解除。そうしないと空のノードになります。
- アクションをクリアし、
pose_bone.driver_remove(...)を実行し、ポーズの両端でrotation_euler[0]にキーフレームを打ちます。 export_skins=True、export_animations=True、export_animation_mode="ACTIONS"、export_yup=Trueでエクスポート。- 復元: アクションを再割り当て、ベイクを削除、ウィジェットを再リンク、ドライバーを再追加、
frame_set(1)、保存。
「サポートされていないコンストレイントのためアニメーションをベイクしています」という警告は想定内です。
レンダリング(オーナーのみ)
トリガー: オーナーが明示的にレンダリングを要求、またはプレビュー画像/動画を依頼した場合。自分の判断でレンダリングしたり、検証としてレンダリングしたりしないでください。
Blender 5.4 では EEVEE が BLENDER_EEVEE(BLENDER_EEVEE_NEXT ではない)として公開されているため、バージョン固有の名前をハードコーディングするのではなく、列挙型から選択します。glTFシーンにはカメラもライトもありません — 最初に Render_Setup コレクション内に作成します。
import bpy, math, os
scene = bpy.context.scene
engines = [i.identifier for i in bpy.types.RenderSettings.bl_rna.properties["engine"].enum_items]
scene.render.engine = next(e for e in ("BLENDER_EEVEE", "BLENDER_EEVEE_NEXT") if e in engines)
if scene.camera is None:
cam_data = bpy.data.cameras.new("Preview_Cam")
cam_data.type = "ORTHO"
cam_data.ortho_scale = 1.0
cam = bpy.data.objects.new("Preview_Cam", cam_data)
scene.collection.objects.link(cam)
cam.location = (0.0, -2.0, -0.055)
cam.rotation_euler = (math.radians(90), 0.0, 0.0)
scene.camera = cam
if not any(o.type == "LIGHT" for o in bpy.data.objects):
light_data = bpy.data.lights.new("Preview_Key", "AREA")
light_data.energy = 300
light_data.size = 2.0
light = bpy.data.objects.new("Preview_Key", light_data)
scene.collection.objects.link(light)
light.location = (1.5, -2.0, 1.5)
light.rotation_euler = (math.radians(55), 0.0, math.radians(35))
scene.render.resolution_x = 1920
scene.render.resolution_y = 1080
scene.render.resolution_percentage = 100
scene.render.image_settings.file_format = "PNG"
scene.render.filepath = "/abs/project/render/preview.png"
bpy.ops.render.render(write_still=True)
result = {"image": scene.render.filepath,
"size": os.path.getsize(scene.render.filepath),
"engine": scene.render.engine, "camera": scene.camera.name}
このパスのルール: 事前に .blend を保存し、<project>/render/ 内に書き込み、絶対パスとファイルサイズを報告し、クライアントタイムアウトを延長し、未保存の変更があるファイルのヘッドレスレンダリングを決して開始しない。
Blender 5.4 の落とし穴
| 症状 | 原因 | 修正 |
|---|---|---|
| ドライバーが何も変更しない | depsgraphが評価されていない | scene.frame_set(f) |
Action.fcurves がない | スロット化アクション | act.layers[0].strips[0].channelbags[*].fcurves、または scripts/action_compat.py |
| リグが動かない、エラーなし | 割り当てられたアクションにこのIDにバインドされたスロットがない | assign_action() / animation_data.action_slot を設定 |
fcurves.new(action_group=...) でTypeError | 5.4のキーワードは group_name | cb.fcurves.new(path, index, group_name="...") |
asset.mark() のポーリングが失敗する | オペレーターがアウトライナー選択を読み取る | obj.asset_mark() API |
| プロパティキーフレームが無視される | 誤ったデータパス | '["open"]' |
.001 アクションサフィックス | 名前の衝突 | まずソースアクションの名前を変更 |
| GLB内のウィジェット | オブジェクトがまだシーンコレクションにある | エクスポート中にリンク解除 |
Unrecognized command | --factory-startup / 拡張機能オフ | オンラインで再起動 |
| 自動起動がサイレントに失敗 | ポートが使用中 | ポートを解放して再起動(再試行なし) |
| レンダー列挙型エラー | 誤ったエンジン名 | 列挙型から BLENDER_EEVEE を選択 |
enum "OCTAHEDRAL" not found | アーマチュア表示はデータ、オブジェクトではない | rig.data.display_type = "OCTAHEDRAL" |
bpy.context.window が None | バックグラウンドビルドにはウィンドウがない | window_manager.windows でガード |
| FBX再インポートでキャラクターが浮く | インポーターがルートを接続ボーンとマークし、その変換を削除する | ラウンドトリップではなく scripts/inspect_fbx.py でファイルを検証 |
成果物
.blend— 信頼できるリグ、静止フレームで保存、README_RIGテキストブロックを含む。.glb— スキニング+アニメーション済み、再インポートで検証済み。- プロジェクトフォルダ内の
README.mdに、ピボット、ボーン、プロパティ、角度、数値を記載。