tanqiu/assets/resources/data/excel/BallController配置说明.md

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目录下运行导入脚本：

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 库
   • 检查文件路径是否正确

依赖安装

如果缺少依赖库，请运行：

pip install pandas openpyxl

与原系统的区别

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

技术实现

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

---

最后更新: 2024年 版本: 1.0