blender-physics-simulation

Blender 物理演算・シミュレーションのエキスパート

概要

このスキルでは、Blender 5.x の物理シミュレーションについて、剛体ダイナミクス、クロス、流体（Mantaflow の煙／火／液体）、ソフトボディ、パーティクルシステム、フォースフィールド、ベイク／キャッシュ、およびシミュレーション設定の Python による自動化に関する専門的なガイダンスを提供します。リファレンスファイルには、物理タイプの完全なカタログと Python API の使用パターンが記載されています。

MCP を優先するアプローチ

剛体／クロス／流体シミュレーションの設定、キャッシュのベイク、実行中の Blender セッションからの結果の直接取得には、公式 Blender MCP Server（Blender Lab、Blender 5.1 以降）を優先してください。MCP サーバーに接続されていない場合に限り、Python スクリプトの出力に切り替えてください。

検出方法： セッション開始時に、名前が execute_blender_code、get_objects_summary、または search_api_docs に一致するツールを探してください。これらは公式の blender-mcp サーバーのツールです。いずれかがあれば、MCP を利用できます。

このスキルで使用するツール：

• execute_blender_code — ライブセッションで bpy Python を実行します（主な操作）
• get_objects_summary、get_object_detail_summary — 変更を加える前にシーンの状態を調べます
• get_blendfile_summary_datablocks / _missing_files / _of_linked_libraries / _path_info / _usage_guess — ファイルの内容を一覧表示します
• search_api_docs、get_python_api_docs、search_manual_docs — 呼び出す前に正しい API／オペレーター名を確認します
• get_screenshot_of_window_as_image / _as_json、get_screenshot_of_area_as_image — 画面の結果を確認します
• jump_to_tab_by_name、jump_to_tab_by_space_type、jump_to_view3d_object_by_name、jump_to_view3d_object_data_by_name — 変更が見えるように UI を操作します
• render_thumbnail_to_path、render_viewport_to_path — 簡易的な視覚的フィードバックを取得します

ワークフロー： get_*／search_* ツールで調査 → execute_blender_code で変更 → スクリーンショットまたは概要ツールで確認します。失敗箇所を特定しやすくするため、コードブロックは小さく、冪等性を保ってください。

セットアップについては、docs/blender-mcp-setup.md を参照してください。

タスクの判断ツリー

• 「オブジェクトを落下／衝突させる」 -> 剛体の設定を参照
• 「クロス／布をシミュレーションする」 -> クロスシミュレーションを参照
• 「煙／火を作成する」 -> 流体シミュレーション（ガス）を参照
• 「液体／水をシミュレーションする」 -> 流体シミュレーション（液体）を参照
• 「パーティクルエフェクト（雨、火花など）」 -> パーティクルシステムを参照
• 「風／重力／乱流を追加する」 -> フォースフィールドを参照
• 「ソフト／ゼリー状の物理演算」 -> ソフトボディを参照
• 「シミュレーションをベイク／キャッシュする」 -> ベイクとキャッシュを参照
• 「シミュレーションが動作しない」 -> デバッグのセクションを参照

剛体の設定

アクティブ剛体（落下、衝突）

import bpy

obj = bpy.context.active_object

# Add rigid body
bpy.ops.rigidbody.object_add(type='ACTIVE')
rb = obj.rigid_body

rb.mass = 1.0
rb.friction = 0.5
rb.restitution = 0.5        # Bounciness (0-1)
rb.collision_shape = 'CONVEX_HULL'  # BOX, SPHERE, CAPSULE, CYLINDER, CONE, CONVEX_HULL, MESH, COMPOUND
rb.use_margin = True
rb.collision_margin = 0.04

# Damping
rb.linear_damping = 0.04
rb.angular_damping = 0.1

# Deactivation (sleep when slow)
rb.use_deactivation = True
rb.deactivation_linear_threshold = 0.4
rb.deactivation_angular_threshold = 0.5

パッシブ剛体（静止コライダー）

bpy.ops.rigidbody.object_add(type='PASSIVE')
rb = obj.rigid_body
rb.collision_shape = 'MESH'  # Use mesh shape for ground/walls
rb.friction = 0.5
rb.restitution = 0.0

# Animated passive (keyframe-driven)
rb.kinematic = True
# Keyframe kinematic on/off for switching between animated and simulated

剛体ワールド

scene = bpy.context.scene

# Create rigid body world if not exists
if scene.rigidbody_world is None:
    bpy.ops.rigidbody.world_add()

rbw = scene.rigidbody_world
rbw.time_scale = 1.0
rbw.substeps_per_frame = 10
rbw.solver_iterations = 10
rbw.use_split_impulse = True

# Point cache
rbw.point_cache.frame_start = 1
rbw.point_cache.frame_end = 250

剛体コンストレイント

# Create empty for constraint
bpy.ops.object.empty_add(location=(0, 0, 0))
empty = bpy.context.active_object

bpy.ops.rigidbody.constraint_add(type='FIXED')
# Types: FIXED, POINT, HINGE, SLIDER, PISTON, GENERIC, GENERIC_SPRING, MOTOR

rbc = empty.rigid_body_constraint
rbc.object1 = bpy.data.objects["Object1"]
rbc.object2 = bpy.data.objects["Object2"]

# For HINGE:
rbc.use_limit_ang_z = True
rbc.limit_ang_z_lower = -1.5708
rbc.limit_ang_z_upper = 1.5708

# Breaking
rbc.use_breaking = True
rbc.breaking_threshold = 100.0

クロスシミュレーション

import bpy

obj = bpy.context.active_object

# Add cloth physics
bpy.ops.object.modifier_add(type='CLOTH')
cloth = obj.modifiers["Cloth"]
settings = cloth.settings
collision = cloth.collision_settings

# Quality
settings.quality = 5              # Simulation quality (steps/frame)
settings.time_scale = 1.0

# Physical properties
settings.mass = 0.3               # Fabric weight (kg)
settings.tension_stiffness = 15.0  # Resistance to stretching
settings.compression_stiffness = 15.0
settings.shear_stiffness = 5.0
settings.bending_stiffness = 0.5   # Resistance to bending (higher = stiffer)
settings.tension_damping = 5.0
settings.compression_damping = 5.0
settings.shear_damping = 5.0
settings.bending_damping = 0.5

# Air resistance
settings.air_damping = 1.0

# Collision
collision.use_collision = True
collision.distance_min = 0.015     # Min distance from colliders
collision.use_self_collision = True
collision.self_distance_min = 0.015
collision.self_friction = 5.0

# Pinning (vertex group)
settings.vertex_group_mass = "Pin"  # Vertex group name — weight 0 = fully pinned

クロスプリセット

スタイル	mass	tension	bending	air_damping
シルク	0.1	5	0.05	1
コットン	0.3	15	0.5	1
デニム	0.5	40	10	1
レザー	0.5	80	150	1
ゴム	0.3	15	25	1

コリジョンオブジェクト

# Add collision to objects that cloth/particles should interact with
bpy.ops.object.modifier_add(type='COLLISION')
collision = obj.modifiers["Collision"]
settings = collision.settings

settings.thickness_outer = 0.02
settings.thickness_inner = 0.2
settings.cloth_friction = 5.0
settings.damping = 0.0

流体シミュレーション（Mantaflow）

ドメインの設定

import bpy

# Create domain (must be mesh object, typically a cube)
bpy.ops.mesh.primitive_cube_add(size=4)
domain = bpy.context.active_object
domain.name = "FluidDomain"

bpy.ops.object.modifier_add(type='FLUID')
fluid = domain.modifiers["Fluid"]
fluid.fluid_type = 'DOMAIN'

domain_settings = fluid.domain_settings
domain_settings.domain_type = 'GAS'  # GAS (smoke/fire) or LIQUID

# Resolution
domain_settings.resolution_max = 64      # Voxel resolution (32-256 typical)
domain_settings.use_adaptive_domain = True

# Cache
domain_settings.cache_frame_start = 1
domain_settings.cache_frame_end = 250
domain_settings.cache_type = 'REPLAY'     # REPLAY, MODULAR, ALL

煙／火（ガスドメイン）

domain_settings.domain_type = 'GAS'
domain_settings.use_noise = True          # Enable noise detail
domain_settings.noise_scale = 2           # Noise resolution multiplier

# Display
domain_settings.display_thickness = 1.0
domain_settings.slice_per_voxel = 5

# Dissolution
domain_settings.use_dissolve_smoke = True
domain_settings.dissolve_speed = 5

# Fire
domain_settings.burning_rate = 0.75
domain_settings.flame_smoke = 1.0
domain_settings.flame_vorticity = 0.5
domain_settings.flame_max_temp = 1.5

液体ドメイン

domain_settings.domain_type = 'LIQUID'
domain_settings.use_mesh = True           # Generate mesh surface
domain_settings.mesh_concave_upper = 3.5
domain_settings.mesh_concave_lower = 0.5
domain_settings.mesh_particle_radius = 1.0

# Particle type
domain_settings.use_spray_particles = True
domain_settings.use_foam_particles = True
domain_settings.use_bubble_particles = True

# Viscosity
domain_settings.viscosity_base = 1.0
domain_settings.viscosity_exponent = 6   # Water: base=1, exp=6

フローオブジェクト（エミッター）

bpy.ops.object.modifier_add(type='FLUID')
fluid = obj.modifiers["Fluid"]
fluid.fluid_type = 'FLOW'

flow = fluid.flow_settings
flow.flow_type = 'SMOKE'         # SMOKE, FIRE, BOTH, LIQUID
flow.flow_behavior = 'INFLOW'   # INFLOW, OUTFLOW, GEOMETRY
flow.use_absolute = False
flow.temperature = 1.0           # Smoke temperature
flow.smoke_color = (0.7, 0.7, 0.7)
flow.density = 1.0
flow.fuel_amount = 0.5           # For fire

# Surface emission
flow.surface_distance = 1.5
flow.volume_density = 0.0        # 0 = surface only, 1 = volume fill

# Animated source
flow.use_particle_size = False

エフェクター（フォース）

bpy.ops.object.modifier_add(type='FLUID')
fluid = obj.modifiers["Fluid"]
fluid.fluid_type = 'EFFECTOR'

effector = fluid.effector_settings
effector.effector_type = 'COLLISION'  # COLLISION or GUIDE
effector.surface_distance = 0.0
effector.use_effector = True

ソフトボディ

import bpy

obj = bpy.context.active_object

bpy.ops.object.modifier_add(type='SOFT_BODY')
sb = obj.modifiers["Softbody"].settings

# Object properties
sb.mass = 1.0
sb.friction = 0.5

# Goal (stiffness toward original shape)
sb.use_goal = True
sb.goal_default = 0.7           # 0 = fully soft, 1 = rigid
sb.goal_spring = 0.5
sb.goal_friction = 0.5
sb.vertex_group_goal = "Goal"   # Vertex group for per-vertex goal

# Edges (spring connections)
sb.use_edges = True
sb.pull = 0.5                   # Spring stiffness (pull)
sb.push = 0.5                   # Spring stiffness (push)
sb.damping = 5.0
sb.plastic = 0                  # Permanent deformation
sb.bending = 0.1                # Bending stiffness
sb.spring_length = 0            # 0 = use original edge lengths

# Self-collision
sb.use_self_collision = False
sb.ball_size = 0.49
sb.ball_stiff = 1.0
sb.ball_damp = 0.5

# Solver
sb.step_min = 1
sb.step_max = 5
sb.use_auto_step = True
sb.error_threshold = 0.1

パーティクルシステム

エミッターパーティクル

import bpy

obj = bpy.context.active_object

# Add particle system
bpy.ops.object.particle_system_add()
ps = obj.particle_systems[-1]
settings = ps.settings

settings.type = 'EMITTER'
settings.count = 1000
settings.frame_start = 1
settings.frame_end = 100
settings.lifetime = 50
settings.lifetime_random = 0.5

# Emission
settings.emit_from = 'FACE'     # VERT, FACE, VOLUME
settings.use_modifier_stack = True

# Velocity
settings.normal_factor = 1.0     # Emit along normals
settings.tangent_factor = 0.0
settings.object_align_factor = (0, 0, 0)
settings.factor_random = 0.5

# Physics
settings.physics_type = 'NEWTON'  # NO, NEWTON, KEYED, BOIDS, FLUID
settings.mass = 1.0
settings.particle_size = 0.05
settings.size_random = 0.5
settings.use_multiply_size_mass = False

# Gravity
settings.effector_weights.gravity = 1.0

# Display
settings.display_size = 0.05
settings.display_method = 'DOT'  # NONE, DOT, CIRC, CROSS, AXIS, RENDER

ヘアーパーティクル

settings.type = 'HAIR'
settings.hair_length = 0.5
settings.hair_step = 5            # Number of segments
settings.root_radius = 1.0
settings.tip_radius = 0.0
settings.use_hair_bspline = True

# Children
settings.child_type = 'INTERPOLATED'  # NONE, SIMPLE, INTERPOLATED
settings.child_nbr = 50            # Viewport children
settings.rendered_child_count = 100 # Render children
settings.child_length = 1.0
settings.child_radius = 0.1
settings.clump_factor = 0.0
settings.clump_shape = 0.0
settings.roughness_1 = 0.0
settings.roughness_2 = 0.0

レンダー設定

settings.render_type = 'HALO'    # NONE, HALO, LINE, PATH, OBJECT, COLLECTION
# For mesh instances:
settings.render_type = 'OBJECT'
settings.instance_object = bpy.data.objects["InstanceMesh"]
# For collection instances:
settings.render_type = 'COLLECTION'
settings.instance_collection = bpy.data.collections["MyCollection"]
settings.use_whole_collection = True
settings.use_rotation_instance = True
settings.use_scale_instance = True

フォースフィールド

フォースフィールドの追加

import bpy

# Force field types (add as empty or to existing object)
bpy.ops.object.effector_add(type='FORCE')  # Attract/repel
# Types: FORCE, WIND, VORTEX, MAGNETIC, HARMONIC, CHARGE, LENNARDJ,
#         TEXTURE, GUIDE, BOID, TURBULENCE, DRAG, SMOKE

field = bpy.context.active_object.field

# Common properties
field.type = 'FORCE'
field.strength = 5.0               # Negative = attract
field.flow = 0.0                   # Outward flow
field.noise = 0.0                  # Random noise factor
field.seed = 0
field.use_max_distance = True
field.distance_max = 10.0
field.use_min_distance = False
field.falloff_type = 'SPHERE'      # SPHERE, TUBE, CONE
field.falloff_power = 2.0          # Distance falloff exponent

よくあるフォースフィールドの設定

# Wind
bpy.ops.object.effector_add(type='WIND')
field = bpy.context.active_object.field
field.strength = 10.0
field.noise = 2.0                  # Gusty wind
field.flow = 0.5

# Turbulence
bpy.ops.object.effector_add(type='TURBULENCE')
field = bpy.context.active_object.field
field.strength = 5.0
field.size = 1.0                   # Turbulence scale
field.flow = 0.5

# Vortex
bpy.ops.object.effector_add(type='VORTEX')
field = bpy.context.active_object.field
field.strength = 5.0
field.inflow = 0.0                 # Inward pull

# Drag
bpy.ops.object.effector_add(type='DRAG')
field = bpy.context.active_object.field
field.linear_drag = 0.1
field.quadratic_drag = 0.0        # Velocity-dependent drag

ベイクとキャッシュ

剛体のベイク

scene = bpy.context.scene
rbw = scene.rigidbody_world

rbw.point_cache.frame_start = 1
rbw.point_cache.frame_end = 250

# Free existing cache
bpy.ops.ptcache.free_bake_all()

# Bake
bpy.ops.ptcache.bake_all(bake=True)

流体のベイク

# For fluid domain
domain = bpy.data.objects["FluidDomain"]
fluid = domain.modifiers["Fluid"]
ds = fluid.domain_settings

ds.cache_frame_start = 1
ds.cache_frame_end = 250

# Bake data (must select domain first)
bpy.context.view_layer.objects.active = domain
bpy.ops.fluid.bake_data()

# Bake noise (for gas)
bpy.ops.fluid.bake_noise()

# Bake mesh (for liquid)
bpy.ops.fluid.bake_mesh()

# Bake particles (spray/foam/bubble)
bpy.ops.fluid.bake_particles()

# Free caches
bpy.ops.fluid.free_data()
bpy.ops.fluid.free_noise()
bpy.ops.fluid.free_mesh()
bpy.ops.fluid.free_particles()

クロス／ソフトボディ／パーティクルのベイク

# Cloth and soft body use point cache
# Select object, then bake
bpy.ops.ptcache.bake(bake=True)  # Bake active cache
bpy.ops.ptcache.free_bake()       # Free active cache
bpy.ops.ptcache.bake_all(bake=True)  # Bake all caches
bpy.ops.ptcache.free_bake_all()       # Free all caches

デバッグ

よくある問題

• シミュレーションが実行されない：フレーム範囲を確認してください。ドメイン／ワールドが存在することを確認してください。再生を開始するか、ベイクしてください。
• オブジェクト同士がすり抜ける：衝突形状の精度を上げ（複雑な形状には MESH を使用）、サブステップ数を増やし、タイムスケールを下げてください。
• クロスが爆発する：タイムスケールを下げ、品質ステップ数を増やし、衝突オブジェクトとの初期交差がないか確認し、衝突距離を増やしてください。
• 流体がドメインから漏れる：ドメインがすべてのフローオブジェクトを完全に囲む必要があります。解像度を上げてください。
• パーティクルがフォースフィールドを無視する：パーティクルシステムのエフェクターの重みを確認してください。フォースフィールドが同じコレクション／レイヤーにあることを確認してください。
• シミュレーション結果が毎回異なる：シード値を設定してください。決定論的な設定になっていることを確認してください。シミュレーションをベイクしてください。
• シミュレーションが遅い：解像度（流体）を下げ、パーティクル数を減らし、衝突マージン（剛体）を増やし、より単純な衝突形状を使用してください。

パフォーマンスのヒント

1. 剛体：可能な場合は単純な衝突形状（Box、Sphere）を使用してください。MESH 形状は処理負荷が高くなります。
2. クロス：反復作業では品質値を下げ、最終レンダー時にのみ上げてください。可能であればメッシュ密度を下げてください。
3. 流体：解像度がパフォーマンスを左右する主な要因です。プレビューでは 32-64、最終出力では 128-256 を使用してください。適応ドメインを有効にしてください。
4. パーティクル：ビューポートの表示数をレンダー数より少なくしてください。ビューポートでの子パーティクル数を制限してください。
5. 全般：レンダリング前にシミュレーションをベイクしてください。ベイク済みのシミュレーションは、再生が高速になります。

物理リファレンス

すべての物理タイプの完全なカタログ、プロパティ一覧、設定の詳細については、references/physics_reference.mdを参照してください。

Python API リファレンス

剛体、クロス、流体、パーティクル、フォースフィールドのセットアップを含む、Python API の完全なパターンについては、references/python_api.mdを参照してください。

Blender 5.1 に関する注意事項

Blender 5.1 では、物理 API に大きな変更はありません。既存の物理シミュレーション API（剛体、クロス、流体、ソフトボディ、パーティクル）は変更されていません。すべての物理システムに、軽微な安定性の向上とバグ修正が適用されています。スクリプト環境の変更については、blender-python-scripting スキルにある Python 3.13 の一般的な注意事項を参照してください。