blender-simulation

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Simulation

模拟(Simulation)

The execution model is in
blender-core
. Procedural sim zones are in
blender-geometry-nodes
.
执行模型位于
blender-core
。程序化模拟区域位于
blender-geometry-nodes
。

One call

一次调用完成

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
steps through every frame in order (this works headless for point caches and GN simulation zones) and reports final positions and
min_z
, so you can verify contact.
--to-keys
turns rigid-body motion into keyframes for engines.
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
则把刚体运动转换为关键帧供引擎使用。

Choose the solver

选择求解器

NeedUse
Falling/stacking/destructionRigid Body (Bullet). Pre-fracture with Cell Fracture (extension) or GN Voronoi
Clothing, flags, drapes (production-proven)Classic Cloth modifier + Collision modifiers
New node-based cloth/hair, custom forces, procedural setupsCloth Dynamics (Experimental) / Hair Dynamics assets (5.2, XPBD)
Liquids, smoke, fireMantaflow fluid domain + flow/effector (
fluid.bake_all
)
Hair groomsCurves objects + hair node assets (
procedural_hair_node_assets
), Hair Dynamics for motion
Growth, trails, custom per-frame logicGN Simulation zone
Soft jiggle for gamesbones with spring/jiggle in-engine, or Wiggle-style constraints baked to keys
需求使用方案
下落/堆叠/破坏刚体(Bullet)。破坏前先用 Cell Fracture(扩展)或 GN Voronoi 预切分
衣物、旗帜、垂坠(生产验证方案)经典 Cloth 修改器 + Collision 修改器
新的基于节点的布料/头发、自定义力、程序化搭建Cloth Dynamics(实验性) / Hair Dynamics 资产(5.2,XPBD)
液体、烟雾、火焰Mantaflow 流体域 + flow/effector(
fluid.bake_all
)
头发造型曲线对象 + 头发节点资产(
procedural_hair_node_assets
),配合 Hair Dynamics 做运动
生长、拖尾、自定义逐帧逻辑GN Simulation 区域
游戏中的柔软抖动骨骼配合引擎内的 spring/jiggle,或将 Wiggle 式约束烘焙为关键帧

Rigid bodies

刚体

  • Real scale and real mass matter: mass = volume × density (wood 500–700, concrete 2400, steel 7850, plastic 950 kg/m³). The script computes it.
  • Collision shape:
    CONVEX_HULL
    for dynamic objects (fast, stable),
    MESH
    only for passive concave colliders, and primitives (
    BOX
    ,
    SPHERE
    ,
    CAPSULE
    ) when they fit.
  • Stability: substeps 10 and iterations 10 (set by the script). Use a small collision margin (1 mm). Avoid objects starting interpenetrated.
  • Export: bake to keyframes (
    --to-keys
    ; the built-in
    rigidbody.bake_to_keyframes
    needs a UI, so the script samples
    matrix_world
    itself), then export the actions (
    blender-export-pipelines
    ).
  • 真实比例与真实质量很重要:质量 = 体积 × 密度(木材 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
    ),然后导出 action(
    blender-export-pipelines
    )。

Classic cloth

经典布料

  • Presets (from Blender's): cotton, denim, leather, rubber, silk. The mesh needs even quad density (2–5 cm edges for clothing). Use a subdivided plane or retopologized garment, never ngons.
  • Pinning: vertex group with weight 1 = pinned (
    settings.vertex_group_mass
    ). Animate pinned verts with hooks/armature.
  • Collisions: colliders get a
    COLLISION
    modifier (thickness 1–5 mm), plus self-collision for folds. Raise
    quality
    (steps) for fast motion.
  • Apply cloth as a shape (
    modifier_apply_as_shapekey
    ) or bake to an Alembic/point cache for render. Games: bake to bones, or apply a static drape.
  • 预设(Blender 自带):cotton、denim、leather、rubber、silk。网格需要均匀的四边面密度(衣物建议边长 2–5 cm)。使用细分平面或重拓扑的服装模型,切勿使用 n-gon。
  • 固定(Pinning):权重为 1 的顶点组即被固定(
    settings.vertex_group_mass
    )。可通过 hooks/骨架驱动被固定的顶点。
  • 碰撞:碰撞体添加
    COLLISION
    修改器(厚度 1–5 mm),并为褶皱开启自碰撞。快速运动时提高
    quality
    (步数)。
  • 可将布料应用为形状(
    modifier_apply_as_shapekey
    ),或烘焙为 Alembic/点缓存用于渲染。游戏中:烘焙到骨骼,或直接应用静态垂坠。

Node-based dynamics (5.2, experimental)

基于节点的动态(5.2,实验性)

  • Assets live in
    datafiles/assets/nodes/geometry_nodes_dynamics_assets.blend
    :
    Cloth Dynamics (Experimental)
    ,
    Hair Dynamics
    ,
    Collider
    ,
    Set Effector
    ,
    Custom Force
    ,
    Custom Effector
    . The script appends them.
  • Cloth inputs include
    Pin Group
    (attribute),
    Stretchiness
    ,
    Bendiness
    ,
    Substeps
    (5),
    Constraint Steps
    (15),
    Mass
    ,
    Friction
    ,
    Collision Radius
    ,
    Linear Damping
    ,
    Gravity
    ,
    Tearing
    (+ mode/threshold),
    Effectors Collection
    ,
    Effectors
    (bundle).
  • Colliders: put a
    Collider
    modifier on each collider object and add those objects to the collection fed into
    Effectors Collection
    (the script does both).
  • Hair: Add → Empty Hair sets up the surface +
    Capture Rest Geometry
    . Hair Dynamics reads the rest/deformed surface through geometry bundles.
  • Limits (5.2): no self-collision yet, no built-in wind/turbulence (build a
    Custom Force
    ). Interfaces may change, so pin the Blender version in production.
  • The solver itself (
    GeometryNodeXPBDSolver
    ) takes a
    World
    bundle,
    Delta Time
    ,
    Substeps
    ,
    Constraint Iterations
    . Building directly on it is advanced; start from the assets.
  • 资产位于
    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
    (bundle)。
  • 碰撞体:为每个碰撞体对象添加
    Collider
    修改器,并把它们加入提供给
    Effectors Collection
    的集合中(脚本会同时完成这两步)。
  • 头发:Add → Empty Hair 会建立表面与
    Capture Rest Geometry
    。Hair Dynamics 通过几何 bundle 读取静止/变形后的表面。
  • 限制(5.2):尚不支持自碰撞,也没有内置的风/湍流(需自行构建
    Custom Force
    )。接口可能变化,生产环境请锁定 Blender 版本。
  • 求解器本身(
    GeometryNodeXPBDSolver
    )接受
    World
    bundle、
    Delta Time
    、
    Substeps
    、
    Constraint Iterations
    。直接基于它搭建属于进阶用法,建议从资产入手。

Fluids (Mantaflow) quick setup

流体(Mantaflow)快速配置

Domain object (
FLUID
modifier
fluid_type="DOMAIN"
,
domain_type="LIQUID"|"GAS"
), resolution 64 preview / 128–256 final, cache directory set and
cache_type="ALL"
for headless; flow objects
fluid_type="FLOW"
(
flow_type
LIQUID/SMOKE/FIRE,
flow_behavior
INFLOW/GEOMETRY); obstacles
EFFECTOR
. Bake with
bpy.ops.fluid.bake_all()
under a context override with the domain active. This is slow. Test at low resolution first.
域对象(
FLUID
修改器
fluid_type="DOMAIN"
,
domain_type="LIQUID"|"GAS"
),预览分辨率 64,最终 128–256,设置好缓存目录并设
cache_type="ALL"
以支持无头模式;flow 对象
fluid_type="FLOW"
(
flow_type
为 LIQUID/SMOKE/FIRE,
flow_behavior
为 INFLOW/GEOMETRY);障碍物为
EFFECTOR
。在激活域对象的 context override 下用
bpy.ops.fluid.bake_all()
进行烘焙。这很耗时,先在低分辨率下测试。

Rules

规则

  • Simulations are frame-rate and scale dependent. Set
    scene.render.fps
    and the scale before tuning.
  • Always bake before rendering/exporting, and never rely on viewport playback order.
  • GN simulation zones: bake per modifier (
    mod.bakes
    ,
    object.geometry_node_bake_single
    ), or step frames sequentially (script) in background.
  • Point caches in background: stepping frames from
    frame_start
    fills the cache.
    ptcache.bake_all(bake=True)
    needs a valid context.
  • Verify with
    look(mode="frames")
    plus the numbers (
    min_z
    ≈ the collider top = contact, no tunnelling).
  • 模拟结果依赖帧率与比例。调参前先设定
    scene.render.fps
    与缩放。
  • 渲染/导出前务必烘焙,绝不要依赖视口播放顺序。
  • GN 模拟区域:按修改器烘焙(
    mod.bakes
    、
    object.geometry_node_bake_single
    ),或在后台按顺序逐帧推进(脚本方式)。
  • 后台点缓存:从
    frame_start
    起逐帧推进即可填充缓存。
    ptcache.bake_all(bake=True)
    需要有效的 context。
  • 用
    look(mode="frames")
    配合数值验证(
    min_z
    ≈ 碰撞体顶部 = 接触成功,无穿透)。

Gotchas

常见坑

  • Objects tunnelling through colliders: thin colliders, too few substeps, or too-fast motion. Thicken, raise substeps/quality, or use a bigger collision distance.
  • Exploding cloth at frame 1: starting interpenetration or a zero-area face. Run
    blender-asset-qa
    , offset the start.
  • Rigid body world cache ranges are separate from the scene range (the script syncs them).
  • Changing anything (frame range, settings) invalidates caches. Re-bake.
  • 物体穿透碰撞体:碰撞体过薄、子步过少或运动过快。加厚碰撞体、提高子步/quality,或增大碰撞距离。
  • 布料在第 1 帧爆炸:初始相互穿插或存在零面积面。运行
    blender-asset-qa
    ,并偏移起始位置。
  • 刚体世界缓存范围与场景范围是独立的(脚本会同步二者)。
  • 任何改动(帧范围、设置)都会使缓存失效,必须重新烘焙。