tanqiu/assets/resources/data/excel/多配置表管理工具使用说明.md

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

概述

游戏配置管理工具是一个图形界面工具，支持读取和管理多种类型的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. 启动工具

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

   pip install pandas openpyxl
   

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

3. 数据格式：

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

4. JSON结构：

   • 纵向表格：直接更新JSON对象的属性
   • 横向表格：更新JSON数组（如enemies、weapons）

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

扩展配置

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

'新配置表.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中的数据格式
   • 确认数值类型参数不包含文本

日志信息

工具运行时会在控制台输出详细的日志信息，包括：

• 配置映射检测结果
• 文件读取状态
• 数据转换过程
• 错误和警告信息

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