blender-simulation

シミュレーション

実行モデルは blender-core にあります。プロシージャルシミュレーションゾーンは blender-geometry-nodes にあります。

1 回の呼び出し

scripts/sim_setup.py -- --rigid --active Crate1 Crate2 --passive Floor --density 500 --frames 1 120 --bake --to-keys
scripts/sim_setup.py -- --cloth Flag --preset cotton --pin Pin --colliders Pole --bake
scripts/sim_setup.py -- --gn-cloth Sheet --colliders Table --set Bendiness=0.5 Stretchiness=0.1 --bake

--bake はすべてのフレームを順番に処理し（ポイントキャッシュと GN シミュレーションゾーンの両方でヘッドレス動作します）、最終位置と min_z を報告するため、接触を確認できます。--to-keys は剛体の動きをエンジン用のキーフレームに変換します。

ソルバーを選ぶ

必要な用途	使用するもの
落下／積み重ね／破壊	剛体（Bullet）。Cell Fracture（拡張機能）または GN Voronoi で事前に破砕します
衣服、旗、ドレープ（実制作で実績あり）	クラシックな Cloth モディファイア＋Collision モディファイア
新しいノードベースの布／髪、カスタムフォース、プロシージャルセットアップ	Cloth Dynamics (Experimental) ／ Hair Dynamics アセット（5.2、XPBD）
液体、煙、炎	Mantaflow の流体ドメイン＋フロー／エフェクター（fluid.bake_all）
ヘアグルーミング	カーブオブジェクト＋ヘアノードアセット（procedural_hair_node_assets）、動きには Hair Dynamics
成長、トレイル、フレームごとのカスタムロジック	GN シミュレーションゾーン
ゲーム用のソフトな揺れ	エンジン内のスプリング／揺れを設定したボーン、またはキーフレームにベイクした Wiggle 風のコンストレイント

剛体

• 実際のスケールと質量が重要です。質量 = 体積 × 密度（木材 500–700、コンクリート 2400、鋼鉄 7850、プラスチック 950 kg/m³）。スクリプトが計算します。
• 衝突形状：動的オブジェクトには CONVEX_HULL（高速で安定）、凹形コライダーにはパッシブオブジェクトでのみ MESH を使用し、適合する場合はプリミティブ（BOX、SPHERE、CAPSULE）を使用します。
• 安定性：サブステップ 10、反復 10（スクリプトで設定）。衝突マージンは小さく（1 mm）します。オブジェクト同士が食い込んだ状態で開始しないようにします。
• エクスポート：キーフレームにベイクし（--to-keys。組み込みの rigidbody.bake_to_keyframes は UI が必要なため、スクリプトが matrix_world を直接サンプリングします）、その後アクションをエクスポートします（blender-export-pipelines）。

クラシックな布

• プリセット（Blender のもの）：コットン、デニム、レザー、ゴム、シルク。メッシュは均一な四角形密度が必要です（衣服の場合、辺の長さは 2–5 cm）。サブディバイドした平面またはリトポロジー済みの衣服を使用し、N ゴンは使わないでください。
• ピン留め：ウェイト 1 の頂点グループがピン留めされます（settings.vertex_group_mass）。フック／アーマチュアでピン留めした頂点をアニメーションさせます。
• 衝突：コライダーに COLLISION モディファイア（厚さ 1–5 mm）を設定し、折り目にはセルフコリジョンも追加します。動きが速い場合は quality（ステップ数）を増やします。
• 布をシェイプとして適用する（modifier_apply_as_shapekey）か、レンダー用に Alembic／ポイントキャッシュにベイクします。ゲームではボーンにベイクするか、静的なドレープとして適用します。

ノードベースのダイナミクス（5.2、実験的）

• アセットは datafiles/assets/nodes/geometry_nodes_dynamics_assets.blend にあります：Cloth Dynamics (Experimental)、Hair Dynamics、Collider、Set Effector、Custom Force、Custom Effector。スクリプトがこれらを追加します。
• 布の入力には Pin Group（属性）、Stretchiness、Bendiness、Substeps（5）、Constraint Steps（15）、Mass、Friction、Collision Radius、Linear Damping、Gravity、Tearing（モード／しきい値を含む）、Effectors Collection、Effectors（バンドル）があります。
• コライダー：各コライダーオブジェクトに Collider モディファイアを設定し、そのオブジェクトを Effectors Collection に渡すコレクションに追加します（スクリプトが両方を行います）。
• 髪：Add → Empty Hair でサーフェスと Capture Rest Geometry を設定します。Hair Dynamics はジオメトリバンドルを介してレストサーフェス／変形サーフェスを読み取ります。
• 制限（5.2）：セルフコリジョンはまだなく、組み込みの風／乱流もありません（Custom Force を作成してください）。インターフェースは変更される可能性があるため、実制作では Blender のバージョンを固定してください。
• ソルバー本体（GeometryNodeXPBDSolver）は World バンドル、Delta Time、Substeps、Constraint Iterations を受け取ります。これを直接使って構築するのは上級者向けです。まずはアセットから始めてください。

流体（Mantaflow）のクイックセットアップ

ドメインオブジェクト（FLUID モディファイア fluid_type="DOMAIN"、domain_type="LIQUID"|"GAS"）、解像度はプレビューで 64、最終版で 128～256、キャッシュディレクトリを設定し、ヘッドレス実行では cache_type="ALL" にします。フローオブジェクトは fluid_type="FLOW"（flow_type は LIQUID/SMOKE/FIRE、flow_behavior は INFLOW/GEOMETRY）、障害物は EFFECTOR にします。ドメインをアクティブにしたコンテキストオーバーライド内で bpy.ops.fluid.bake_all() を実行してベイクします。時間がかかるため、まず低解像度でテストしてください。

ルール

• シミュレーションはフレームレートとスケールに依存します。調整を始める前に scene.render.fps とスケールを設定してください。
• レンダリング／エクスポートの前には必ずベイクし、ビューポートの再生順序に依存しないでください。
• GN シミュレーションゾーンは、モディファイアごとにベイクする（mod.bakes、object.geometry_node_bake_single）か、バックグラウンドでフレームを順番に進めて（スクリプトで）ください。
• バックグラウンドでのポイントキャッシュは、frame_start からフレームを進めるとキャッシュが生成されます。ptcache.bake_all(bake=True) には有効なコンテキストが必要です。
• look(mode="frames") と数値を併用して確認してください（min_z ≈ コライダーの上端 = 接触。すり抜けがないこと）。

注意事項

• オブジェクトがコライダーをすり抜ける場合：コライダーが薄すぎる、サブステップが少なすぎる、または動きが速すぎることが原因です。厚みを増やす、サブステップ／品質を上げる、または衝突距離を大きくしてください。
• フレーム 1 でクロスが爆発する場合：開始時にオブジェクトがめり込んでいるか、面の面積がゼロになっています。blender-asset-qa を実行し、開始位置をずらしてください。
• リジッドボディワールドのキャッシュ範囲はシーン範囲とは別です（スクリプトで同期されます）。
• 何かを変更すると（フレーム範囲、設定など）、キャッシュは無効になります。再ベイクしてください。