Community影像github.com

Blender 即時骨架綁定

透過官方 Blender MCP 橋接,在使用者開啟的 Blender 應用程式中即時進行 3D 模型的骨架綁定、編輯、驗證與匯出。適用於骨架、蒙皮、機械/鉸鏈骨架、驅動器、自訂屬性控制、評估網格驗證、烘焙 glTF 匯出,以及僅在擁有者明確要求時才進行渲染。

Blender 即時骨架綁定 是什麼?

此技能讓 AI 代理能夠直接控制使用者正在使用的 Blender 即時 GUI 實例(而非背景批次處理),透過官方的 Blender MCP 橋接(`bl_ext.blenderlab.mcp`)在 `127.0.0.1:9876` 上進行通訊。它強制執行一套嚴格的規則集:絕不在未經使用者同意的情況下關閉或渲染、始終操作評估的依賴圖網格、在編輯前後將視窗聚焦在資產上,並以數值方式驗證每個步驟。此技能涵蓋了完整的骨架綁定流程:從匯入 glTF、檢查幾何形狀、以基於零件的方法設計骨架拓撲(機械資產的剛性零件/權重/骨頭)、使用布林運算準備網格、設定自訂屬性驅動器(例如 0-1 的「開合」),到最後匯出經過驗證的 glTF。驗證使用基於閾值的檢查(例如,網格偏差 < 1e-5、流形邊界、骨骼 vs 地面碰撞的逐幀網格測量),並包含專用腳本 `scripts/glb_qa.py`(無需 Blender)來驗證 GLB 的二進位格式完整性。對於角色動畫,它使用雙骨頭 IK 來解決腿部運動,而不是手動設定關鍵影格。該技能也針對 Blender 5.x 的插槽式動作模型(`action_compat.py`)提供了具體的相容性處理,並記錄了常見的陷阱(例如,未綁定的動作插槽、錯誤的 `fcurves.new()` 關鍵字參數、背景建置中的 `bpy.context.window` 為 `None`)。最終產出物包括一個 `.blend` 檔案(附有 README_RIG 文字區塊)、一個經過驗證的 `.glb` 檔案,以及一份包含樞紐點、骨頭、屬性和角度的專案 `README.md`。渲染僅應擁有者的明確要求執行,使用 EEVEE,並在渲染前建立相機和燈光。

相容平台✓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 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

Blender 即時骨架綁定 是做什麼的?

驅動使用者正在觀看的 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 安裝的,則儲存庫根目錄在此文件的上三層目錄 (skills/blender-live-rigging/SKILL.md)。

嚴格規則

  1. 僅限即時 GUI。 確認 bpy.app.background == False。絕不在使用者工作時關閉 Blender;如果必須因連接埠衝突而重新啟動,請先儲存 .blend 檔案,然後重新開啟同一個檔案。
  2. 除非擁有者要求,否則不進行渲染。 預設驗證是數值化的:頂點座標、寬度、面積、比例。當擁有者明確要求渲染時,請在即時工作階段中進行(請參閱「按需渲染」)。
  3. 將視窗聚焦在你編輯的內容上,在更改前後:選取物件/骨頭,將一個設為啟用,執行 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) 在每個里程碑儲存;將 deliverables 保留在專案資料夾內。
  7. 一個 execute = 一個原子性、冪等的步驟,並返回證明該步驟的度量。
  8. 在網格上測量接觸地面的部分,而不是骨頭。 骨頭末端可能位於鞋底上方 0.4 stud,因此骨頭末端閘道通過,但靴子卻陷入地面。使用評估網格的最低世界頂點。

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. 決定骨架拓撲

對於機械資產:剛性零件、剛性權重、每個零件一個骨頭。對於剪刀/鉗子形狀,對角線配對零件(左手柄 + 右鉗口半部),使手柄和鉗口一起打開;中線分割會使鉗口在手柄打開時閉合。

將鉸鏈樞紐點放在手柄相接處,並將接縫切割也放在那裡,並對齊骨頭,使 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. 控制項與動畫

一個自訂屬性(open,0–1)透過簡單的驅動程式表達式驅動每個骨頭,並加上 LIMIT_ROTATION 作為安全網。在驅動 rotation_euler 之前設定 rotation_mode = "XYZ"。為循環動作對屬性(而非骨頭)設定關鍵影格,並設定 BEZIER + AUTO_CLAMPED。

6. 驗證(在聲稱成功前通過閘道)

度量閾值
與原始網格的靜止偏差< 1e-5
循環接縫(最後影格 vs 第一影格)0
打開/關閉的面積比0.99–1.01
手柄和鉗口均向外移動> 0
已加權重的頂點100%
非流形 / 零面積面0
最低變形頂點 vs 地板≥ −0.006,站立腳 0 ± 0.006

scripts/verify_rig_glb.py 在獨立的 Blender 程序中重新匯入匯出的 GLB(絕不干擾即時工作階段),並列印節點/蒙皮/動畫計數以及在第 1/15/30/60 影格的寬度。

對於運動,使用針對腳踝目標的雙骨頭 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 仍然負責活動部件的寬度測量。閘道、基準線以及它們捕獲的五個故意損壞的檔案: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          # 否則 dataclasses/imports 會看到重複
spec.loader.exec_module(mod)
result = mod.main(save=True)             # 返回測量閘道的字典

保留 __main__ 給背景執行 (blender -b file.blend --python walk_cycle.py -- --save),並從橋接呼叫 main(),這樣一個腳本就能同時服務兩個路徑。

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,並且骨架保持靜止且無錯誤(頭部位於 4.0 而非動畫的 3.92)。閘道: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 陷阱

症狀原因修正方法
驅動器無任何變化依賴圖未評估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() 輪詢失敗運算子讀取的是 Outliner 選取內容obj.asset_mark() API
屬性關鍵影格被忽略資料路徑錯誤'["open"]'
.001 動作後綴名稱衝突先重新命名原始動作
GLB 中的小工具物件仍在場景集合中在匯出期間取消連結
Unrecognized command--factory-startup / 擴充功能關閉使用 online mode 重新啟動
自動啟動靜默連接埠已被佔用釋放連接埠,重新啟動(不重試)
渲染列舉錯誤引擎名稱錯誤從列舉中選擇 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,包含樞紐點、骨頭、屬性、角度、數值。

相關技能