blender-physics-workflow

Blender Physics Nodes Workflow Skill (Blender 5.2.1 LTS)

本スキルは Blender 5.2.1 LTS（検証済みビルド 9e2066aef7ef）を対象とし、インタラクティブな3Dビューポート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個の編集可能サブグループ

1. Wrapper層 (PNW_Wrapper_<obj>_<mod>)：モディファイアに直接マウントされる外側ノードグループであり、物理ワークベンチとCLIの統一的インターフェースを公開します。ジオメトリノードエディタで挿入されたカスタムノード（例：User_Added_Realize）や新規インターフェース（例：User Custom Scale）は、後続の update / parameters / bake 操作で完全に保持されます。
2. 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）を自動的に実行します。
3. 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）

---

二、サポートされる3ドメイン、6プリセット、明示的ブリッジ

• 契約識別子：BLENDER_PHYSICS_WORKFLOW_CONTRACT_V1 (schema_version: 1.0)
• 3ドメインとプリセット (PRESET_DEFINITIONS)：
  1. rigid_scatter：rigid_drop_pack（複数インスタンスの散乱衝突と停止）、rigid_chain_pendulum（アンカー距離制約チェーンペンデュラム）
  2. cloth_rope：cloth_banner_wind（上端自動アンカー+風による布）、rope_catenary_swing（CURVE の自動パイプメッシュ出力対応）
  3. 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（レシート/ボリューム対応エクスポート）

---

三、インタラクティブ N-Panel ワークベンチの使用

• パネル位置：3D Viewport -> N-Panel -> Physics Nodes（VIEW_3D_PT_physics_nodes_workbench）
• コアオペレーター：
  • pnw.load_preset_defaults：プリセットデフォルトパラメータの読み込み
  • pnw.build_workflow：3層ノードツリーの構築と初期状態の書き込み
  • pnw.update_parameters：ユーザーノードと外部接続を保持したままワークフロー/パラメータを更新、パラメータハッシュ変更時に古いキャッシュを自動無効化
  • pnw.bake_cache / pnw.invalidate_cache：DISK ベイクの管理（Windows MAX_PATH 超過を防ぐため短いパス < 240 文字）
  • 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 主要な注意点リスト

1. Modifier入力代入：getattr(mod.properties.inputs, identifier).value = val を使用して代入する必要があります（mod[id] = val は不可）。メタデータは obj[f"pnw_state_json__{mod.name}"] に保存されます。
2. Nodes 入力ソケット化プロパティ：CollectionInfo["Separate Children"]、InstanceOnPoints["Pick Instance"]、CurveToMesh["Fill Caps"]、PointsToVolume["Resolution Mode"]、VolumeToMesh["Resolution Mode"] はすべてノードプロパティではなく node.inputs[...] にあります。GeometryNodeSetShadeSmooth の最初の入力ポート名は "Mesh" です。
3. Alembicエクスポートキーワード：Blender 5.2.1 の bpy.ops.wm.alembic_export には visible_objects_only パラメータはありません。同期限定で書き込みを完了させるには、as_background_job=False を明示的に設定する必要があります。
4. 物理ローカル座標とPBD収縮防止：Simulation Zone はオブジェクトのローカル座標系で動作します。アンカーと地面は Self Object 位置を差し引く必要があります。布/ロープのPBDブレンドは、相対静止変位 (p_pred - pnw_rest_pos) に作用させる必要があり、絶対座標を直接平滑化してはいけません。