Blender 物理節點工作流程技能 (Blender 5.2.1 LTS)
本技能面向 Blender 5.2.1 LTS（已驗證建構 9e2066aef7ef），提供互動式三維視口 N 面板工作台（Physics Nodes）以及隔離的外部批次 CLI 入口 <REPO_ROOT>/tools/physics_workflow_cli_v1/cli.py。
[!IMPORTANT] 並發與安全邊界：物理工作流程插件與 CLI 完全獨立於
tools/blenderctl/、tools/geometry_nodes_workflow_addon/和tools/uv_workflow_addon/執行；嚴禁未授權覆蓋來源.blend檔案或跳過 SHA-256 校驗與磁碟快取失效檢查。
一、核心節點架構：Wrapper + Core + 12 個可編輯子組
- Wrapper 層 (
PNW_Wrapper_<obj>_<mod>)：直接掛載在修改器上的外層節點組，暴露物理工作台和 CLI 的統一介面。在 Geometry Nodes Editor 中插入的自訂節點（如User_Added_Realize）與新增介面（如User Custom Scale）會在後續update/parameters/bake操作中完整保留。 - Core 層 (
PNW_Core_<obj>_<mod>)：包含 1 個根級GeometryNodeSimulationInput/Output+ 尾部GeometryNodeBake+ 內部GeometryNodeRepeatInput/Output（Substeps = 1..8,dt_sub = Delta Time / Substeps），確保單bake_id與磁碟快取精確 1:1 綁定；並自動完成世界錨點轉局部空間（Anchor - self_info.Location）、世界地面轉局部Ground Z以及生成網格材質透傳（GeometryNodeSetMaterial）。 - 12 個模組化無狀態子組 (
PN_*)：- 力場：
PN_Force_GravityDrag、PN_Force_WindTurbulence - 碰撞：
PN_Collide_GroundPlane、PN_Collide_MeshSurface（含距離閾值屏蔽，防止有限網格外無限延展） - 約束：
PN_Constraint_PinAnchor、PN_Constraint_DistanceChain - 步進求解器：
PN_Solver_RigidScatterStep、PN_Solver_ClothRopeStep（基於p_pred - pnw_rest_pos相對靜止位移的 PBD 模糊與速度耦合，不收縮不垮塌）、PN_Solver_FluidParticleStep - 後處理：
PN_Post_InstanceRigid、PN_Post_FluidSDFMesh（PointsToSDFGrid -> GridToMesh）、PN_Post_SmokeVolume（PointsToVolume + VolumeToMesh）
- 力場：
二、支援的三域、6 套預設與顯式橋接
- 合約識別：
BLENDER_PHYSICS_WORKFLOW_CONTRACT_V1(schema_version: 1.0) - 三域與預設 (
PRESET_DEFINITIONS)：rigid_scatter：rigid_drop_pack（多實例散落碰撞與停靠）、rigid_chain_pendulum（錨點距離約束鏈擺）cloth_rope：cloth_banner_wind（頂邊自動錨定風吹布料）、rope_catenary_swing（支援CURVE自動轉管網輸出）fluid_emission：fluid_fountain_sdf（粒子發射 + 碰撞 + SDF 表面化網格）、smoke_plume_volume（浮力 + 風渦旋 + 體積/預覽網格）
- Solver Bridge Modes：
GN_NATIVE（預設純節點核心）、XPBD_ASSET_BRIDGE（橋接 Blender 5.2 內置Cloth Dynamics (Experimental)）、BULLET_BRIDGE（橋接RigidBodyWorld）、MANTAFLOW_BRIDGE（橋接原生FLUID修改器）。 - Export Formats：
NONE、STATIC_MESH、ALEMBIC（.abc動畫序列）、OPENVDB（回執/Volume 適配匯出）。
三、互動式 N-Panel 工作台使用
- 面板位置：
3D Viewport -> N-Panel -> Physics Nodes（VIEW_3D_PT_physics_nodes_workbench） - 核心操作算子：
pnw.load_preset_defaults：載入預設預設參數pnw.build_workflow：建構三層節點樹並寫入初始狀態pnw.update_parameters：保留使用者節點與外部連線更新工作流程/參數，參數哈希變化時自動失效舊快取pnw.bake_cache/pnw.invalidate_cache：管理DISK烘焙（短路徑< 240字元防止 WindowsMAX_PATH越界）pnw.inspect_workflow：統計實體數、位移、接地穿透與快取一致性
四、CLI Overlay 自動化排程 (physics_workflow_cli_v1)
入口：<REPO_ROOT>/tools/physics_workflow_cli_v1/cli.py。執行依賴 Blender 可執行檔時，先設定環境變數 BLENDER_PATH（或 BLENDERCTL_BLENDER）。
1. 查詢合約與預設
python tools/physics_workflow_cli_v1/cli.py describe
2. 單場景建構、烘焙、冷重開核驗與 Alembic 匯出 (run)
$env:BLENDER_PATH = "<path-to-blender-5.2.1>"
python tools/physics_workflow_cli_v1/cli.py run `
--request "path/to/request.json" `
--jobs-dir "./jobs/my-job" `
--timeout-seconds 300
最小 request.json 範例：
{
"schema_version": "1.0",
"operation": "build",
"preset_id": "fluid_fountain_sdf",
"target_object": "Fountain_Emitter",
"collider_object": "Dome_Deflector",
"input_blend": "./input/scene_in.blend",
"output_blend": "./output/scene_baked.blend",
"bake": true,
"verify_cold_reopen": true,
"export_format": "ALEMBIC",
"export_path": "./output/fluid.abc",
"parameters": {
"substeps": 3,
"frame_start": 1,
"frame_end": 120,
"emit_rate": 16,
"emit_speed": 1.85,
"particle_radius": 0.15,
"sdf_voxel_size": 0.07,
"contact_thickness": 0.15,
"ground_z": 0.0
}
}
3. 參數掃描 (sweep) 與批次處理 (batch)
sweep：在基礎請求上注入參數變體列表，並列比較位移/速度/穩定性。batch：順序/隔離執行多個獨立.blend仿真作業並輸出彙總回執。
五、Blender 5.2.1 關鍵避坑清單
- Modifier 輸入賦值：必須透過
getattr(mod.properties.inputs, identifier).value = val賦值（不可用mod[id] = val），元資料儲存在obj[f"pnw_state_json__{mod.name}"]。 Nodes輸入插座化屬性：CollectionInfo["Separate Children"]、InstanceOnPoints["Pick Instance"]、CurveToMesh["Fill Caps"]、PointsToVolume["Resolution Mode"]、VolumeToMesh["Resolution Mode"]均位於node.inputs[...]而非節點屬性；GeometryNodeSetShadeSmooth首輸入埠名為"Mesh"。- Alembic 匯出關鍵字：Blender 5.2.1
bpy.ops.wm.alembic_export無visible_objects_only參數，需明確設定as_background_job=False以保證同步落地。 - 物理局部座標與 PBD 防止收縮：
Simulation Zone內部運行於物體局部座標系，錨點與地面需扣除Self Object位置；布料/繩索 PBD 模糊必須作用於相對靜止位移(p_pred - pnw_rest_pos)，不可直接平滑絕對座標。