# BallController Excel配置系统使用说明

## 概述

本系统为 `BallController.ts` 提供了基于Excel的配置管理方案，解决了原有复杂Excel表格导入困难的问题。

## 文件结构

```
excel/
├── BallController标准配置表.xlsx    # 标准化配置表格
├── import_ball_config.py            # 配置导入脚本
├── BallController配置说明.md         # 本说明文档
└── BallController配置表.xlsx         # 原始复杂表格（已废弃）
```

## 配置参数说明

### 速度相关
- `baseSpeed`: 球的基础速度 (默认: 30)
- `maxReflectionRandomness`: 反射随机性最大值 (默认: 0.2)

### 防围困机制
- `antiTrapTimeWindow`: 防围困时间窗口 (默认: 5秒)
- `antiTrapHitThreshold`: 防围困碰撞阈值 (默认: 5次)
- `deflectionAttemptThreshold`: 偏转尝试阈值 (默认: 3次)
- `antiTrapDeflectionMultiplier`: 防围困偏转倍数 (默认: 3)

### 发射控制
- `FIRE_COOLDOWN`: 发射冷却时间 (默认: 0.05秒)

### 物理属性
- `ballRadius`: 球的半径 (默认: 25)
- `gravityScale`: 重力缩放 (默认: 0)
- `linearDamping`: 线性阻尼 (默认: 0)
- `angularDamping`: 角阻尼 (默认: 0)

### 碰撞检测
- `colliderGroup`: 碰撞组 (默认: 1)
- `colliderTag`: 碰撞标签 (默认: 1)
- `friction`: 摩擦力 (默认: 0)
- `restitution`: 弹性系数 (默认: 1)
- `sensor`: 是否为传感器 (默认: false)

### 生成参数
- `safeDistance`: 安全距离 (默认: 20)
- `edgeOffset`: 边缘偏移 (默认: 20)
- `maxAttempts`: 最大尝试次数 (默认: 50)

## 使用方法

### 1. 修改配置

1. 打开 `BallController标准配置表.xlsx`
2. 在"数值"列中修改对应参数的值
3. 保存Excel文件

**注意事项：**
- 不要修改"参数名"列的内容
- 布尔值请使用 `true` 或 `false`
- 数值参数请使用数字格式，避免被Excel识别为日期

### 2. 导入配置

在Excel目录下运行导入脚本：

```bash
python import_ball_config.py
```

成功后会看到类似输出：
```
✅ 配置导入成功！
📁 Excel文件: BallController标准配置表.xlsx
📄 JSON文件: ../ballController.json
📊 导入了 19 个配置参数
```

### 3. 验证配置

导入后的JSON配置文件位于：`../ballController.json`

可以检查该文件确认配置是否正确导入。

## 故障排除

### 常见问题

1. **Excel文件格式错误**
   - 确保表格只有两列："参数名" 和 "数值"
   - 不要添加额外的描述列或标题行

2. **数值格式问题**
   - 避免Excel自动将数字识别为日期
   - 布尔值使用 `true`/`false` 而不是 `TRUE`/`FALSE`

3. **导入脚本错误**
   - 确保安装了 `pandas` 和 `openpyxl` 库
   - 检查文件路径是否正确

### 依赖安装

如果缺少依赖库，请运行：
```bash
pip install pandas openpyxl
```

## 与原系统的区别

| 特性 | 原始表格 | 标准表格 |
|------|----------|----------|
| 列数 | 6列（包含描述） | 2列（精简） |
| 格式复杂度 | 高 | 低 |
| 导入成功率 | 低（格式问题） | 高 |
| 维护难度 | 高 | 低 |
| 数据类型错误 | 常见 | 罕见 |

## 技术实现

- **Excel读取**: 使用 `pandas.read_excel()` 读取标准格式表格
- **数据转换**: 自动处理数值和布尔类型转换
- **JSON输出**: 生成符合 `BallControllerConfig` 接口的JSON配置
- **错误处理**: 提供详细的错误信息和验证机制

---

*最后更新: 2024年*
*版本: 1.0*