Community画像github.com

Blender Live Rigging

Blenderのライブインスタンス上で3Dアセットのリギング、編集、検証、エクスポートを実行します。公式のBlender MCPソケットブリッジを使用し、アーマチュア、スキニング、メカニカルリグ、ドライバー、カスタムプロパティ、評価メッシュ検証、ベイクドglTFエクスポートに対応。レンダリングはオーナーが明示的に要求した場合のみ行います。

Blender Live Rigging とは?

このスキルは、ユーザーが開いているBlenderアプリケーションを直接操作し、ライブで3Dアセットのリギング、編集、検証、エクスポートを行うためのものです。公式のBlender MCP拡張機能(bl_ext.blenderlab.mcp)を介して127.0.0.1:9876のソケットで通信します。主な機能には、アーマチュアとスキニング、メカニカル/ヒンジリグ、ドライバー式、カスタムプロパティコントロール、評価メッジ検証、ベイクドglTFエクスポートが含まれます。レンダリングはデフォルトでは無効で、オーナーが明示的に要求した場合のみ実行されます。このスキルは、Claude Code、Cursor、CodexなどのAIエージェントで使用することを想定して設計されており、ユーザーの作業を妨げずにリグ作業を自動化・補助します。

対応✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/andypratama3/blender-mcp/tree/HEAD/skills/blender-live-rigging

Installed? Explore more 画像 skills: steipete/songsee, affaan-m/frontend-design, mattpocock/improve-codebase-architecture · View all 6 →

お気に入りのAIに質問する

このエージェントスキルを事前に読み込んだ状態で新しいチャットを開きます。

ドキュメント

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)。

ハードルール

  1. ライブGUIのみ。 bpy.app.background == False を確認。ユーザーが作業中にBlenderを強制終了しないでください。ポート競合のために再起動が必要な場合は、先に .blend を保存し、同じファイルを開き直してください。
  2. オーナーが依頼しない限りレンダリングしない。 デフォルトの検証は数値ベース:頂点座標、幅、面積、比率。オーナーが明示的にレンダリングを要求した場合のみ、ライブセッションで行います(レンダリングは依頼時のみ参照)。
  3. 編集対象にビューポートをフォーカスする。 変更前後で、オブジェクト/ボーンを選択し、1つをアクティブにし、view3d.view_axis + view3d.view_selected を実行。アセット平面に合った軸を選択(フラットなXZアセットには FRONT)。
  4. 評価メッシュを使用し、オリジナルは決して使用しない: obj.evaluated_get(depsgraph).to_mesh()。
  5. scene.frame_set(f) でドライバー評価を強制する — view_layer.update() だけでは不十分。
  6. bpy.ops.wm.save_as_mainfile(filepath=..., compress=True) でインクリメンタルに保存。マイルストーンごとに実行し、成果物はプロジェクトフォルダ内に保持。
  7. 1回の execute は1つのアトミックでべき等なステップとし、それを証明するメトリクスを返す。
  8. 床に触れる部分はメッシュで測定し、ボーンでは測定しない。 ボーンテールは靴底より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にはドライバー、カスタムプロパティ、コンストレイントがありません。これらをベイクします:

  1. ソースアクションの名前を変更(*_src)し、ベイクされたアクションにクリーンな名前を付けます。
  2. カスタムシェイプウィジェットオブジェクトをリンク解除。そうしないと空のノードになります。
  3. アクションをクリアし、pose_bone.driver_remove(...) を実行し、ポーズの両端で rotation_euler[0] にキーフレームを打ちます。
  4. export_skins=True、export_animations=True、export_animation_mode="ACTIONS"、export_yup=True でエクスポート。
  5. 復元: アクションを再割り当て、ベイクを削除、ウィジェットを再リンク、ドライバーを再追加、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=...) でTypeError5.4のキーワードは group_namecb.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 に、ピボット、ボーン、プロパティ、角度、数値を記載。

関連スキル