blender-simulation

模拟

执行模型位于 blender-core。程序化模拟区域位于 blender-geometry-nodes。

一次调用

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 进行预破碎
服装、旗帜、帷幕（经生产验证）	经典 布料 修改器 + 碰撞修改器
新式基于节点的布料／头发、自定义力、程序化设置	布料动力学（实验性）／头发动力学资源（5.2，XPBD）
液体、烟雾、火焰	Mantaflow 流体域 + 流动／效应器（fluid.bake_all）
头发造型	曲线对象 + 头发节点资源（procedural_hair_node_assets），使用头发动力学制作运动
生长、轨迹、自定义逐帧逻辑	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）。使用细分平面或重拓扑后的服装网格，切勿使用多边面。
• 固定：权重为 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（bundle）。
• 碰撞体：在每个碰撞体对象上添加 Collider 修改器，并将这些对象添加到输入 Effectors Collection 的集合中（脚本会同时完成这两项操作）。
• 头发：Add → Empty Hair 会设置表面并添加 Capture Rest Geometry。头发动力学通过几何 bundle 读取静止／变形后的表面。
• 限制（5.2）：暂不支持自碰撞，也没有内置风力／湍流（请构建 Custom Force）。接口可能会变化，因此生产环境中请固定 Blender 版本。
• 求解器本身（GeometryNodeXPBDSolver）接收 World bundle、Delta Time、Substeps、Constraint Iterations。直接基于它构建属于进阶用法；建议从资源入手。

Fluids（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，偏移起始位置。
• 刚体世界缓存范围独立于场景范围（脚本会同步它们）。
• 更改任何内容（帧范围、设置）都会使缓存失效。请重新烘焙。