# 流体动力学插件使用指南

## 概述

流体动力学插件提供基于物理的流体模拟功能，支持水、油、熔岩等多种流体类型。插件采用SPH（光滑粒子流体动力学）方法实现，能够模拟流体的基本物理行为，包括流动、碰撞、压力和粘性效应。

## 安装和启用

### 1. 插件结构

```
fluid_dynamics/
├── __init__.py
├── plugin.py                 # 插件主入口
├── core/
│   ├── fluid_world.py        # 流体世界管理
│   ├── fluid_solver.py       # 流体求解器
│   ├── fluid_material.py     # 流体材质系统
│   └── fluid_visualizer.py   # 流体可视化
├── components/
│   ├── fluid_emitter.py      # 流体发射器
│   ├── fluid_obstacle.py     # 流体障碍物
│   └── fluid_domain.py       # 流体域
├── utils/
│   ├── math_utils.py         # 数学工具
│   └── performance_utils.py  # 性能工具
└── config/
    └── default_config.json   # 默认配置
```

### 2. 启用插件

在主程序中启用插件：

```python
# 加载插件
fluid_plugin = world.plugin_manager.load_plugin("fluid_dynamics")

# 启用插件
world.plugin_manager.enable_plugin("fluid_dynamics")
```

## 核心功能

### 1. 流体域 (FluidDomain)

定义流体模拟的边界和空间：

```python
from plugins.user.fluid_dynamics.components.fluid_domain import FluidDomain

# 创建流体域
domain = FluidDomain(
    min_bound=Point3(-10, -10, 0),
    max_bound=Point3(10, 10, 20)
)
fluid_world.add_fluid_domain(domain)
```

### 2. 流体发射器 (FluidEmitter)

生成流体粒子：

```python
from plugins.user.fluid_dynamics.components.fluid_emitter import FluidEmitter

# 创建发射器
emitter = FluidEmitter(
    position=Point3(0, 0, 10),
    fluid_world=fluid_world
)
emitter.set_emit_rate(50)  # 每秒发射50个粒子
emitter.set_emit_velocity(Vec3(0, 0, 2))  # 向上发射
fluid_world.add_fluid_emitter(emitter)
```

### 3. 流体障碍物 (FluidObstacle)

定义流体模拟中的障碍物：

```python
from plugins.user.fluid_dynamics.components.fluid_obstacle import FluidObstacle

# 创建障碍物
obstacle = FluidObstacle(
    position=Point3(0, 0, 5),
    size=Vec3(2, 2, 2),
    obstacle_type="box"
)
fluid_world.add_fluid_obstacle(obstacle)
```

### 4. 流体材质 (FluidMaterial)

定义流体的物理和视觉属性：

```python
from plugins.user.fluid_dynamics.core.fluid_material import FluidMaterial

# 创建水材质
water_material = FluidMaterial(
    name="water",
    fluid_type=FluidMaterial.TYPE_WATER
)

# 创建熔岩材质
lava_material = FluidMaterial(
    name="lava", 
    fluid_type=FluidMaterial.TYPE_LAVA
)
```

## 高级功能

### 1. 性能优化

插件提供自适应性能优化：

```python
from plugins.user.fluid_dynamics.utils.performance_utils import FluidPerformanceOptimizer

# 创建性能优化器
optimizer = FluidPerformanceOptimizer(fluid_world)

# 启用性能优化
optimizer.optimize_for_performance()

# 获取性能报告
report = optimizer.get_performance_report()
print(f"当前FPS: {report['current_fps']}")
```

### 2. 可视化控制

调整流体的视觉效果：

```python
# 设置流体颜色
visualizer.set_fluid_color(Vec4(0.0, 0.8, 1.0, 0.7))

# 创建粒子系统
particle_system = visualizer.create_particle_system("fluid_particles", 2000)
```

## API参考

### FluidWorld类

- `add_fluid_domain(domain)`: 添加流体域
- `remove_fluid_domain(domain)`: 移除流体域
- `add_fluid_emitter(emitter)`: 添加发射器
- `remove_fluid_emitter(emitter)`: 移除发射器
- `add_fluid_obstacle(obstacle)`: 添加障碍物
- `remove_fluid_obstacle(obstacle)`: 移除障碍物
- `update(dt)`: 更新流体世界
- `pause(paused)`: 暂停/恢复模拟
- `set_time_scale(scale)`: 设置时间缩放

### FluidSolver类

- `set_viscosity(viscosity)`: 设置粘度
- `set_density(density)`: 设置密度
- `set_gravity(gravity)`: 设置重力
- `solve(dt)`: 执行流体求解

### FluidMaterial类

- `TYPE_WATER`: 水类型
- `TYPE_OIL`: 油类型
- `TYPE_LAVA`: 熔岩类型
- `TYPE_SLIME`: 粘液类型
- `TYPE_BLOOD`: 血液类型
- `get_density()`: 获取密度
- `get_viscosity()`: 获取粘度
- `get_color()`: 获取颜色

## 示例场景

创建一个简单的流体演示：

```python
def create_fluid_demo(world):
    # 1. 获取插件实例
    fluid_plugin = world.plugin_manager.get_plugin("fluid_dynamics")
    fluid_world = fluid_plugin.fluid_world
    
    # 2. 创建流体域
    domain = FluidDomain(Point3(-5, -5, 0), Point3(5, 5, 10))
    fluid_world.add_fluid_domain(domain)
    
    # 3. 创建发射器
    emitter = FluidEmitter(Point3(0, 0, 8), fluid_world)
    emitter.set_emit_rate(30)
    fluid_world.add_fluid_emitter(emitter)
    
    # 4. 创建障碍物
    obstacle = FluidObstacle(Point3(0, 0, 3), Vec3(1, 1, 3), "box")
    fluid_world.add_fluid_obstacle(obstacle)
    
    # 5. 设置求解器
    solver = FluidSolver(fluid_world)
    fluid_world.solver = solver
```

## 故障排除

### 常见问题

1. **性能问题**：
   - 减少粒子数量
   - 降低发射器速率
   - 使用性能优化器

2. **稳定性问题**：
   - 调整时间步长
   - 检查边界条件
   - 验证物理参数

3. **可视化问题**：
   - 检查粒子系统配置
   - 确认渲染节点正确附着
   - 调整透明度和颜色设置

## 配置选项

编辑 `config/default_config.json` 文件可以调整默认参数：

```json
{
  "simulation": {
    "time_step": 0.016,
    "gravity": [0, 0, -9.81],
    "viscosity": 0.001,
    "density": 1000.0
  },
  "performance": {
    "max_particles": 5000,
    "update_frequency": 60
  }
}
```