Blender 的材質、燈光與渲染
你透過 BlenderLab 連線 在用戶的 Blender 中工作。 視埠捕捉與最終渲染是不同的：捕捉顯示的是視埠當下的著色模式，而渲染則使用渲染引擎、燈光與世界。大多數「看起來沒事但渲染錯誤」的問題都源於此。
你的 Blender 連線
你透過 BlenderLab（官方 Blender Lab 伺服器）工作；其工具以 blenderlab_… 為前綴：
- 場景中有什麼：
get_objects_summary；單一物件的詳細資訊：get_object_detail_summary（依name查詢）。檔案（無論是否儲存）及其路徑：get_blendfile_summary_path_info。 - 執行 Python：
execute_blender_code。每次呼叫之間不會保留任何內容（請在每個腳本中攜帶你的輔助函式）；腳本列印的內容會回傳，指派給result的字典會作為資料回傳。其防護機制會拒絕某些運算元（如退出 Blender、回復原廠設定）。 - 查看 3D 視埠：使用
get_screenshot_of_area_as_image並設定area_ui_type: "VIEW_3D"（整個視窗：get_screenshot_of_window_as_image）；將視埠對準某個物件：jump_to_view3d_object_by_name。 - 查詢 Python API：
get_python_api_docs（傳入識別碼，例如bpy.types.BevelModifier）、search_api_docs；手冊：search_manual_docs。 - 快速渲染：
render_thumbnail_to_path、render_viewport_to_path；圖片會存到 Blender 的暫存資料夾，結果會回傳真實路徑。 - 匯出：程式碼（
bpy.ops.export_scene.gltf、bpy.ops.export_scene.fbx）。 - 資產庫與 3D 產生器：無。請自行建立物件，或要求用戶提供要匯入的檔案。
如果這些工具不可用，請停止並告知：用戶必須安裝 BlenderLab 連線（工具 → 連線），將其提供給此代理程式，並讓 Blender 開啟且附加元件的伺服器已啟動。請勿將無法完成的工作描述為已完成。
工作順序
- 觀察：使用場景工具；有哪些物件、哪些已有材質、是否有攝影機、燈光、世界？讀取
bpy.app.version_string及目前的渲染引擎。 - 材質：每種不同表面建立一個材質，以其本質命名（如
Oak_Wood、Brushed_Steel），並在不同物件間重複使用。 - 燈光與世界：在評估任何材質之前先設定燈光與世界：無法在黑暗中評估材質。
- 攝影機：對準主題，使用合理的焦距。
- 測試渲染：小尺寸（25-50% 解析度，少量樣本），觀察後修正。
- 最終渲染：輸出到檔案，並回報路徑、引擎、解析度與時間。
每個步驟的程式碼位於 references/shading-and-render.md。在撰寫第一個腳本前請先開啟該檔案。
材質：常見問題
- 顏色設定在錯誤位置。
material.diffuse_color和object.color僅是視埠顯示顏色：它們不會出現在渲染中。實際渲染的顏色是 Principled BSDF 節點的 Base Color 輸入。若希望實體模式視埠與渲染一致，請兩者都設定。 - Blender 4.0 中輸入名稱變更。
Transmission改為Transmission Weight、Emission改為Emission Color、Specular改為Specular IOR Level、Clearcoat改為Coat Weight、Subsurface改為Subsurface Weight。請透過名稱查詢輸入並確認其存在後再設定；不確定時請使用連線的 API 工具。 - 已建立材質但從未指定。 將材質附加到
obj.data.materials；若同一網格的不同部位使用不同材質，請設定polygon.material_index。 - 依類型而非名稱尋找節點。 該節點僅在英文介面中稱為「Principled BSDF」。請使用
next(n for n in nodes if n.type == 'BSDF_PRINCIPLED')。
| 表面類型 | Principled BSDF 設定 |
|---|---|
| 漆面、塑膠 | Base Color；Roughness 0.3-0.6；Metallic 0 |
| 金屬 | Metallic 1.0；Base Color = 金屬的顏色；Roughness 0.15-0.5 |
| 玻璃 | Transmission Weight 1.0；Roughness 0-0.05；IOR 1.45；需要有世界或燈光才能產生折射內容 |
| 發光 | Emission Color + Emission Strength (1-20) |
| 橡膠、布料、消光 | Roughness 0.8-1.0 |
| 車漆、清漆 | Coat Weight 1.0；Coat Roughness 0.05 |
Metallic 應為 0 或 1，幾乎從不取中間值。純黑色 (0, 0, 0) 與純白色 (1, 1, 1) 的 Base Color 在燈光下看起來不對勁：請維持在約 0.03-0.9 的範圍內。
燈光與世界
- 沒有世界且沒有燈光會導致渲染全黑；而即使有燈光，若世界空無一物，玻璃或鉻金屬在空世界中渲染也會全黑，因為沒有東西可反射或折射。請為世界設定顏色與強度，或使用 HDRI。
- 一個可靠的起點：一個大型區域光作為主光（與物體成 45° 角，位於上方一側）、另一側較弱的補光、後方一道邊緣光，以及強度較低的世界（0.2-0.5）。
- 區域光功率以瓦特為單位，且需要較高數值：距離小型物體 2 公尺的 1 平方公尺區域光約需 100-500 W。太陽光的強度則不同：2-5。
- 物體下方的地面平面可提供接觸陰影；沒有它物體會看起來懸浮在空中。
- HDRI 可一次提供逼真的光線與反射。Blender（MCP for Blender）連線可從 Poly Haven 下載 HDRI：但此為第三方內容，需在 HydraOps 中獲得授權，因此請先詢問。在 BlenderLab 上，請要求用戶提供 HDRI 檔案。
渲染引擎
| EEVEE | Cycles | |
|---|---|---|
| 速度 | 數秒 | 數秒至數分鐘 |
| 用途 | 預覽、風格化、動畫 | 最終靜態圖、玻璃、精確光線 |
| 注意事項 | 反射與折射需啟用光線追蹤；否則玻璃與光滑表面會看起來平淡或有顆粒感 | 噪點：提高樣本數並保持降噪開啟；僅在用戶設定後才使用 GPU |
EEVEE 的引擎識別碼因版本而異（4.2-4.5 為 BLENDER_EEVEE_NEXT，之前與之後為 BLENDER_EEVEE）：參考資料顯示如何無需猜測即可正確設定。請勿變更用戶的渲染裝置或偏好設定。
攝影機
- 若場景中沒有攝影機，請建立一個並設為場景攝影機；除非用戶要求，否則不要移動用戶已放置的攝影機。
- 使用 Track To 約束將攝影機對準主題或空物體；物件使用 50-85 mm，房間與環境使用 24-35 mm。
- 使用小型測試渲染來檢查構圖，而非視埠截圖（除非切換至攝影機視圖，否則視埠並非攝影機）。
渲染
- 渲染到檔案，使用用戶可找到的資料夾中的絕對路徑（若 .blend 已儲存則放在其旁，否則詢問或使用用戶的暫存資料夾），並回報完整路徑。切勿在未告知的情況下覆寫現有檔案。使用程式碼執行（參考資料中有說明）：BlenderLab 自己的渲染工具僅用於快速檢查，無論你給什麼路徑，它們都會寫入 Blender 的暫存資料夾；請回報它們結果中命名的路徑。
- 先進行小型測試。全解析度的 Cycles 渲染可能需要數分鐘，且會在執行期間鎖住 Blender；在開始長時間渲染前請告知用戶。
- 在宣告成功前先查看結果：視埠捕捉不等於渲染。如果你無法自行查看渲染檔案，請坦誠說明，並描述你所設定的內容，而非圖像「看起來如何」。
- 色彩管理：預設的視圖轉換（AgX 或 Filmic）會使強烈顏色去飽和以達到真實感；若需完全匹配的平面圖形顏色，請使用
Standard。
疑難排解
| 症狀 | 常見原因 |
|---|---|
| 渲染全黑 | 無燈光且無世界；攝影機位於物體內部；物件被隱藏不渲染 |
| 物體呈現灰色或白色 | 材質未指定，或顏色設定在 diffuse_color 而非 Base Color |
| 玻璃呈現黑色 | 世界空白；在 EEVEE 中光線追蹤關閉 |
| 呈現粉紅或洋紅色 | 缺少影像紋理檔案 |
| 有顆粒感 | Cycles：樣本數過少或未啟用降噪。EEVEE：光線追蹤關閉，或軟陰影樣本數過低 |
| 平淡、無深度 | 僅有世界光：請加入主光與地面平面 |
| 顏色 washed-out | 視圖轉換：嘗試 Standard，或降低曝光度 |
| 曲面呈現塊狀 | 平面著色：請啟用平滑著色 |
在宣告完成之前
- 每個可見物件都已指定材質，且其 Base Color 已在節點上設定。
- 存在燈光或已發光的世界，以及一個構圖對準主題的攝影機。
- 已將渲染結果寫入檔案，並提供了路徑、引擎與解析度。
- 僅變更了被要求的項目：未刪除物件，也未變更偏好設定。