終極 Blender
一個技能融合了三種套件:el4cteo(經測試的 bpy 腳本 + Blender 5.x 規則)、arjun988(技術美術總監工作流程、90+ 專業與風格指南)以及 kevinbadi(產品相機動畫、Poly Haven、Meshy 照片轉 3D、Three.js 匯出)。
如何使用此檔案:先閱讀它,然後僅開啟路由表中與任務相符的指南。不要載入所有指南。每個指南都包含來自每個來源套件關於該主題的章節。所有路徑均相對於此技能的資料夾(<skill_root>)。
1. 總監工作流程(每個新資產)
分析 → 規劃 → 簡報 → 執行 → 驗證 → 交付
- 分析:資產用途(主角 / 標準 / 背景)、目標(遊戲 / 電影 / 作品集 / 產品影片)、平台(行動裝置 / 遊戲主機 / PC / 網頁 / Roblox)、風格、動畫(靜態 / 已骨架化 / 已動畫)、匯出格式。
- 規劃:從路由表(第 4 節)中挑選指南,並設定多邊形與紋理預算(
refs/shared/polycount-budgets.md)。 - 簡報:對於任何比快速編輯更大的任務,請在觸碰 Blender 之前撰寫一份簡短的生產簡報:資產、預算、使用的指南、階段、匯出目標。
- 執行:透過 MCP 或無頭模式(第 2 節)執行小步驟。在撰寫新程式碼前,優先使用內建腳本。
- 驗證:遵循第 5 節。此步驟為必填。
- 交付:匯出,然後報告數值與檔案路徑。
有附上參考圖像? 遵循 refs/shared/reference-image-match.md:填寫 refs/shared/reference-analysis-template.md,在微調細節前先對齊相機,以螢幕截圖比較反覆迭代,然後對照 refs/shared/visual-match-checklist.md 檢查。
完整總監手冊,包含簡報、多技能食譜與決策樹:refs/director-full.md。
命名:refs/shared/naming-conventions.md · 管線:refs/shared/asset-pipeline.md · MCP:refs/shared/mcp-integration.md、refs/shared/mcp-tools.md。
2. 執行
即時模式(blender-mcp execute_blender_code):以小步驟工作,只印出你需要的內容。要呼叫內建腳本:
import sys, importlib; sys.path.insert(0, r"<skill_root>/scripts")
import qa_check; importlib.reload(qa_check); print(qa_check.run(objects=["Chair"]))
每次 MCP 呼叫都會在新的命名空間中執行,因此每次都需要重新 import。僅在編輯腳本後才使用 reload。
無頭模式(shell,無需 MCP)。這只會印出腳本的 JSON:
python <skill_root>/scripts/run_in_blender.py --blend in.blend <skill_root>/scripts/<script.py> -- --objects Chair --save out.blend
python <skill_root>/scripts/run_in_blender.py --expr "import bpy; print(len(bpy.data.objects))"
Windows:偏好使用 PowerShell。在 Git Bash 中,加上 MSYS_NO_PATHCONV=1 前綴,並使用 $(cygpath -m ~/.claude/skills)/ultimate-blender/...。blender.exe 必須在 PATH 中,或傳遞其路徑。
首次呼叫會話:執行 scripts/env_report.py(版本、引擎、GPU、附加元件、單位、色彩管理)。
節點輔助工具(kevinbadi;它們與連接埠 9876 上的 blender-mcp 通訊):node <skill_root>/scripts/node/<name>.js --help。
3. Blender 5.x 規則(這些規則凌駕於任何指南中的舊有建議之上)
- 資料 API 優先於運算子:使用
bpy.data、bmesh、mesh.attributes以及foreach_get/set(搭配 numpy)。運算子需要上下文,且背景模式沒有 3D 視埠。 - 不可避免的運算子:
with bpy.context.temp_override(object=ob, active_object=ob, selected_objects=[ob], selected_editable_objects=[ob]): bpy.ops...,然後檢查是否為{'FINISHED'}。 - 編輯模式:在編輯模式下,
ob.data是過時的。使用bmesh.from_edit_mesh+update_edit_mesh,或先切換到物件模式。 - 節點:透過
type("BSDF_PRINCIPLED")尋找它們,絕不要用name,因為名稱是本地化的。 - 列舉:從
bl_rna.properties[p].enum_items讀取它們。對於動態列舉(render.engine、view_transform),在try/except TypeError內指定。 - 引擎:
BLENDER_EEVEE、CYCLES、BLENDER_WORKBENCH。GPU:scene.cycles.device="GPU"+ 偏好設定中的compute_device_type。 - 評估後的網格:
ob.evaluated_get(dg).to_mesh(),然後務必to_mesh_clear()。在讀取matrix_world之前,先呼叫view_layer.update()。 - 已釋放的資料:在移除或套用任何項目之前先收集名稱,並且絕不重複使用舊的 Python 參考。
- 名稱:絕不相信 "Cube.001"。明確地重新命名,並使用
bpy.data.objects[name]查詢物件。 - 比例:1 單位 = 1 米。在倒角、骨架、物理、烘焙和匯出之前,套用旋轉和比例。
- 即時會話屬於使用者的工作:絕不執行
read_factory_settings,絕不刪除你未建立的資料,並在進行破壞性批次編輯之前儲存備份(save_as_mainfile(copy=True))。 - 背景 GPU:呼叫
gpu.init()(5.2+)。bgl已不復存在。雕刻模式在-b下會崩潰,因此請使用scripts/sculpt_ops.py。 - 5.x API 中斷:
action.fcurves→ channelbags ·scene.node_tree→scene.compositing_node_group·material.use_nodes已棄用 ·mod["Socket_2"]→mod.properties.inputs.Socket_2.value·BLENDER_EEVEE_NEXT→BLENDER_EEVEE· 布林值FAST→FLOAT· 骨骼圖層 → 骨骼集合 ·bl_info→blender_manifest.toml· 5.3:合成器效果堆疊,VSEEXPAND→RIPPLE。完整表格:refs/blender-core/api-changes-5x.md。程式碼模式:refs/blender-core/bpy-patterns.md。
4. 路由:任務 → 指南(+ 腳本)
| 任務 | 開啟 | 關鍵腳本 |
|---|---|---|
| 單位、命名、集合、資產庫、批次/無頭管線、附加元件/擴充功能 | guides/01-scene-pipeline.md | scene_audit, batch_process, assets/addon_template |
| 硬表面、倒角、布林運算、加權法線、一般建模、程序化建模 | guides/02-modeling-hardsurface.md | apply_stack |
| 道具、套件組合、傢俱、車輛、機甲、建築可視化 | guides/03-props-vehicles-archviz.md | apply_stack, build_pbr_material |
| 雕刻、多精度、重新網格化、生物、怪物 | guides/04-sculpting-creatures.md | sculpt_ops |
| 人類角色、原型、服裝、面部骨架、ARKit / visemes | guides/05-characters-clothing-face.md | garment, shapekeys |
| 毛髮、毛皮、毛髮卡片 | guides/06-hair-groom.md | groom |
| 拓樸、UV 展開、紋理密度、UDIM、光照貼圖 UV | guides/07-retopology-uv.md | auto_retopo, uv_pack, texel_density |
| PBR 材質、磨損與污垢、貼花、修飾條、烘焙 | guides/08-materials-texturing-baking.md | build_pbr_material, smart_material, decal, bake_maps |
| 幾何節點、程序化生成器、散佈 | guides/09-geometry-nodes.md | gn_builder |
| 地形、生物群系、模組化套件、植被、場景佈置 | guides/10-environments-vegetation.md | terrain, scatter, kit_check |
| Rigify、蒙皮、遊戲骨架、關鍵影格、NLA、動作捕捉重定向、循環 | guides/11-rigging-animation.md | rigify_build, bind_mesh, rig_check, stress_poses, retarget, bake_action, loop_check |
| 剛體、布料、流體、破壞、VFX、雨、雪、閃電 | guides/12-simulation-vfx-weather.md | sim_setup, precipitation, surface_weather, lightning |
| 照明佈光、HDRI、外觀開發、相機、一天中的時間、霧、氛圍 | guides/13-lighting-camera-lookdev.md | turntable, scene_mood |
| Cycles/EEVEE 設定、批次渲染、合成器 | guides/14-rendering-compositing.md | render_batch |
| 多邊形預算、LOD、繪製呼叫、碰撞代理 | guides/15-optimization-lod-collision.md | mesh_stats, make_lods |
| 匯出 glTF/FBX/USD 至 Unity、Unreal、Godot、Roblox、網頁/Three.js | guides/16-export-engines.md | export_asset, node/blender-threejs-export.js |
| 交付前 QA(務必執行) | guides/17-qa-review.md | qa_check, review_shots |
| 影片序列器編輯、動態追蹤、相機求解 | guides/18-video-editing-tracking.md | vse_edit, track_camera |
| 產品影片:轉盤、慢速推近、滑軌、搖臂、快慢動作循環、完美循環、產品拋光 | guides/19-product-camera-animations.md | node/blender-product-polish.js, turntable.py |
| Poly Haven HDRIs、紋理、工作室/展間場景、材質變體 | guides/20-polyhaven-assets.md | node/polyhaven-*.js |
照片 → 紋理 3D 模型(Meshy API,需 MESHY_API_KEY) | guides/21-image-to-3d.md | 然後 auto_retopo, qa_check |
| 端到端劇本(道具、角色、Roblox、產品鏡頭) | guides/22-workflow-recipes.md | |
| 可選的外部 WebSocket 工具包(透過 Dev-GOM 附加元件進行 Mixamo 重定向) | guides/23-websocket-toolkit.md | (未內建) |
風格方向:從這些檔案中開啟一個章節,而非整個檔案。
| 風格要求 | 開啟 |
|---|---|
| 風格化、寫實、低多邊形、動漫/漫畫、Q版、卡通、漫畫、手繪、像素、體素、等角、HD-2D、復古 8/16 位元、黑色電影、卡通/NPR、主機世代(PS1–PS5、CRT/VHS) | styles/art-styles.md |
| 恐怖、PSX 恐怖、獨立、拾得錄影、身體、宇宙、民間、吉祥物恐怖、阈限空間、奇怪核 | styles/horror.md |
| 奇幻、科幻/龐克、末世、歷史、生物群系、舒適、黑暗/寫實、超現實、野獸主義、霓虹未來主義 | styles/worlds-moods.md |
| 類型藝術指導:動作、卡牌/放置、銀河城、VN、開放世界、平台、競速、RPG、射擊、魂系、潛行、策略、生存 | styles/game-genres.md |
每個主題的深度參考資料位於 refs/<原始技能名稱>/,指南直接連結到它們。
5. 驗證(在說「完成」之前必須執行)
- 報告數字,而非形容詞:三角面數、物件數、材質數、尺寸(
ob.dimensions)以及寫入的輸出檔案。 - 如果幾何體有變更,執行
scripts/qa_check.py(Z 軸衝突、分離部件、非流形、反轉法線、比例)。 - 檢視結果:MCP
get_viewport_screenshot/look,或無頭模式scripts/review_shots.py的連絡表。 - 對於遊戲資產,針對平台預算執行
scripts/mesh_stats.py,並通過refs/shared/validation-checklist.md檢查。 - 確認匯出的檔案存在且大小不為零。