EG/plugins/user/soft_body_cloth_physics/README.md

# 软体物理和布料模拟插件使用指南

## 简介

软体物理和布料模拟插件为iFlow引擎提供了真实的布料和软体物理模拟功能。该插件基于Bullet物理引擎的软体物理模块，支持多种布料材质和软体类型。

## 功能特性

1. **布料模拟**：
   - 支持多种预定义布料材质（棉布、丝绸、皮革等）
   - 可自定义布料物理参数
   - 支持固定点设置
   - 实时风力影响

2. **软体物理**：
   - 支持多种软体材质（橡胶、果冻、肌肉组织等）
   - 多种形状支持（球体、盒体、绳索等）
   - 可自定义物理参数

3. **调试可视化**：
   - 网格可视化
   - 固定点显示
   - 力和速度向量可视化

## 安装和启用

### 启用插件

在iFlow项目中启用插件：

```python
# 在主程序中启用插件
world = MyWorld()  # 或您的世界对象

# 启用插件系统
world.plugin_manager.enable_plugin_system()

# 加载并启用软体物理和布料模拟插件
cloth_plugin = world.plugin_manager.load_plugin("soft_body_cloth_physics")
if cloth_plugin:
    world.plugin_manager.enable_plugin("soft_body_cloth_physics")
```

## 基本使用

### 创建布料对象

```python
# 获取布料管理器
cloth_manager = world.plugins['soft_body_cloth_physics'].cloth_manager

# 启用布料管理器
cloth_manager.enable()

# 创建布料片
from panda3d.core import NodePath
parent_node = NodePath("cloth_parent")

# 创建一个2x2米的棉布片，分辨率为10x10
cloth_info = cloth_manager.create_cloth_patch(
    parent_node, 
    width=2.0, 
    height=2.0, 
    resolution_x=10, 
    resolution_y=10,
    params={'material': 'cotton'}
)

# 添加固定点（固定四个角）
if cloth_info:
    cloth_manager.add_anchor(cloth_info, 0)  # 左下角
    cloth_manager.add_anchor(cloth_info, 9)  # 右下角
    cloth_manager.add_anchor(cloth_info, 90) # 左上角
    cloth_manager.add_anchor(cloth_info, 99) # 右上角
```

### 创建软体对象

```python
# 获取软体管理器
soft_manager = world.plugins['soft_body_cloth_physics'].soft_body_manager

# 启用软体管理器
soft_manager.enable()

# 创建球形软体
from panda3d.core import Point3
parent_node = NodePath("soft_body_parent")

# 创建一个橡胶球
soft_info = soft_manager.create_soft_body_sphere(
    parent_node,
    radius=0.5,
    resolution=8,
    params={'material': 'rubber'}
)

# 创建绳索软体
rope_info = soft_manager.create_soft_body_rope(
    parent_node,
    point_a=Point3(0, 0, 5),
    point_b=Point3(0, 0, 0),
    resolution=20,
    params={'material': 'rubber'}
)
```

### 使用预定义材质

```python
# 获取材质管理器
from plugins.user.soft_body_cloth_physics.materials.cloth_materials import ClothMaterialManager
material_manager = ClothMaterialManager()

# 获取棉布材质参数
cotton_params = material_manager.get_material("cotton").get_physical_parameters()

# 创建使用特定材质的布料
cloth_info = cloth_manager.create_cloth_patch(
    parent_node, 
    width=2.0, 
    height=2.0, 
    resolution_x=10, 
    resolution_y=10,
    params=cotton_params
)
```

### 调试可视化

```python
# 启用调试可视化
debug_manager = world.plugins['soft_body_cloth_physics'].debug_manager
debug_manager.enable()

# 设置可视化选项
debug_manager.cloth_visualizer.set_visibility_flags(
    mesh=True,      # 显示网格
    anchors=True,   # 显示固定点
    forces=False,   # 不显示力
    velocities=False # 不显示速度
)
```

## 高级功能

### 自定义材质

```python
# 创建自定义布料材质
custom_material = material_manager.create_custom_material(
    "CustomElastic",
    "custom",
    physical_params={
        'density': 0.4,
        'linear_stiffness': 0.9,
        'angular_stiffness': 0.8,
        'volume_stiffness': 0.7,
        'friction': 0.5,
        'restitution': 0.3
    },
    visual_params={
        'color': Vec4(1.0, 0.5, 0.5, 1.0),
        'roughness': 0.6
    }
)

# 注册自定义材质
material_manager.register_material(custom_material)
```

### 实时参数调整

```python
# 动态调整布料参数
if cloth_info:
    cloth_manager.update_cloth_params(cloth_info, {
        'linear_stiffness': 0.9,  # 增加线性刚度
        'friction': 0.8          # 增加摩擦力
    })
```

### 应用外力

```python
# 对软体应用力
from panda3d.core import Vec3
if soft_info:
    soft_manager.apply_force_to_soft_body(
        soft_info['soft_body'], 
        Vec3(0, 0, 100)  # 向上的力
    )
```

## 配置文件

插件的配置存储在 `config/cloth_settings.json` 文件中，可以调整以下参数：

- 物理参数（重力、空气密度等）
- 默认布料和软体参数
- 调试可视化选项

## 性能优化建议

1. **降低分辨率**：对于远距离或不重要的布料，使用较低的分辨率
2. **限制对象数量**：软体物理计算开销较大，避免场景中同时存在过多软体对象
3. **使用LOD**：根据距离动态调整布料分辨率
4. **合理设置参数**：避免过于 stiff 的参数设置，可能导致仿真不稳定

## 故障排除

### 常见问题

1. **布料穿模**：
   - 增加布料的体积保持系数
   - 调整时间步长参数

2. **性能问题**：
   - 降低布料分辨率
   - 减少同时模拟的软体对象数量

3. **对象不响应物理**：
   - 确保插件已正确启用
   - 检查物理世界是否正常工作

### API参考

详细API文档请参考插件源代码中的类和方法注释。