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)。
嚴格規則
- 僅限即時 GUI。 確認
bpy.app.background == False。絕不在使用者工作時關閉 Blender;如果必須因連接埠衝突而重新啟動,請先儲存.blend檔案,然後重新開啟同一個檔案。 - 除非擁有者要求,否則不進行渲染。 預設驗證是數值化的:頂點座標、寬度、面積、比例。當擁有者明確要求渲染時,請在即時工作階段中進行(請參閱「按需渲染」)。
- 將視窗聚焦在你編輯的內容上,在更改前後:選取物件/骨頭,將一個設為啟用,執行
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)在每個里程碑儲存;將 deliverables 保留在專案資料夾內。 - 一個
execute= 一個原子性、冪等的步驟,並返回證明該步驟的度量。 - 在網格上測量接觸地面的部分,而不是骨頭。 骨頭末端可能位於鞋底上方 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 沒有驅動器、自訂屬性或約束。將它們烘焙:
- 重新命名原始動作(
*_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 陷阱
| 症狀 | 原因 | 修正方法 |
|---|---|---|
| 驅動器無任何變化 | 依賴圖未評估 | 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() 輪詢失敗 | 運算子讀取的是 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,包含樞紐點、骨頭、屬性、角度、數值。