# 游戏配置管理工具使用说明

## 概述

游戏配置管理工具是一个图形界面工具，支持读取和管理多种类型的Excel配置表，并将配置数据导入到对应的JSON文件中。

## 支持的配置表类型

### 1. BallController配置表 (纵向表格)
- **文件**: `BallController配置表.xlsx`
- **格式**: 纵向表格，参数名在第一列，参数值在第二/三列
- **对应JSON**: `ballController.json`
- **参数类型**: 包含球控制器的各种物理参数（速度、阻尼、碰撞等）

### 2. 敌人配置表 (横向表格)
- **文件**: `敌人配置表.xlsx`
- **格式**: 横向表格，第一行是字段名，下面是数据行
- **对应JSON**: `enemies.json`
- **参数类型**: 敌人ID、名称、类型、生命值、攻击力等

### 3. 武器配置表 (横向表格)
- **文件**: `方块武器配置表_更新_v2.xlsx`
- **格式**: 横向表格，第一行是字段名，下面是数据行
- **对应JSON**: `weapons.json`
- **参数类型**: 武器ID、名称、类型、伤害、射速等

### 4. 关卡配置表 (横向表格)
- **文件**: `关卡配置表_完整版_更新_v2.xlsx`
- **格式**: 横向表格，第一行是字段名，下面是数据行
- **对应JSON**: `levels/` 目录下的各个关卡JSON文件
- **参数类型**: 关卡ID、名称、场景、难度、奖励等

## 使用步骤

### 1. 启动工具
```bash
cd d:\CocosGame\Pong\assets\resources\data\excel
python config_manager.py
```

### 2. 选择配置文件
1. 在左侧文件列表中浏览项目文件
2. 选择要导入的Excel配置表文件
3. 工具会自动识别文件类型并匹配对应的JSON文件

### 3. 预览配置
- 选择文件后，右侧预览区域会显示：
  - Excel表格的配置数据
  - 当前JSON文件的配置内容
  - 检测到的配置映射信息

### 4. 导入配置
1. 确认预览内容正确后，点击"导入配置"按钮
2. 工具会自动备份原有配置文件
3. 将Excel数据转换并合并到JSON文件中
4. 显示导入结果和更新的参数数量

## 配置映射规则

工具会根据文件名自动检测配置映射：

| Excel文件名包含 | 对应JSON文件 | 表格类型 |
|----------------|-------------|----------|
| `BallController配置表` | `ballController.json` | 纵向 |
| `敌人配置` | `enemies.json` | 横向 |
| `武器配置` | `weapons.json` | 横向 |
| `关卡配置` | `levels/` 目录 | 横向 |

## 数据转换规则

### 纵向表格 (如BallController)
- 第一列：参数名
- 第二列：参数值
- 第三列：默认值（如果存在，优先使用）
- 自动进行类型转换（int、float、bool、string）

### 横向表格 (如敌人、武器)
- 第一行：字段名
- 第二行：字段说明（跳过）
- 第三行及以后：数据记录
- 每行数据转换为一个JSON对象

## 备份机制

- 每次导入前自动备份原有JSON文件
- 备份文件命名格式：`原文件名_backup_before_import_时间戳.json`
- 备份文件保存在同一目录下

## 错误处理

- 文件不存在：显示错误提示
- 格式错误：跳过无效数据行，继续处理其他数据
- 类型转换失败：使用默认值或跳过该参数
- 权限问题：显示具体错误信息

## 注意事项

1. **依赖库要求**：需要安装 `pandas` 和 `openpyxl`
   ```bash
   pip install pandas openpyxl
   ```

2. **文件路径**：确保Excel文件路径正确，支持中文路径

3. **数据格式**：
   - 纵向表格：参数名不能重复
   - 横向表格：第一行必须是字段名
   - 空值会被自动跳过

4. **JSON结构**：
   - 纵向表格：直接更新JSON对象的属性
   - 横向表格：更新JSON数组（如enemies、weapons）

5. **多工作表支持**：对于包含多个工作表的Excel文件，工具会自动选择合适的工作表

## 扩展配置

如需添加新的配置表类型，可以在 `config_manager.py` 中的 `config_mappings` 字典中添加新的映射：

```python
'新配置表.xlsx': {
    'json_path': self.project_root / "assets/resources/data/新配置.json",
    'param_types': {
        '参数1': str,
        '参数2': int,
        '参数3': float,
        # ...
    },
    'format_type': 'horizontal'  # 或 'vertical'
}
```

## 故障排除

### 常见问题

1. **pandas未安装**
   - 错误：`ModuleNotFoundError: No module named 'pandas'`
   - 解决：`pip install pandas openpyxl`

2. **文件读取失败**
   - 检查文件路径是否正确
   - 确认文件没有被其他程序占用
   - 检查文件权限

3. **配置映射未找到**
   - 工具会使用默认的BallController映射
   - 可以手动添加新的配置映射

4. **数据类型转换错误**
   - 检查Excel中的数据格式
   - 确认数值类型参数不包含文本

### 日志信息

工具运行时会在控制台输出详细的日志信息，包括：
- 配置映射检测结果
- 文件读取状态
- 数据转换过程
- 错误和警告信息

通过查看这些日志可以快速定位问题所在。