# 迷宫游戏 - 新按钮功能说明

## 🎮 更新后的按钮功能

### 1. 🚀 Start Button (开始按钮)
- **功能**: 生成全新的随机迷宫
- **操作**: 点击"开始"按钮
- **结果**: 
  - 生成新的迷宫布局
  - 自动计算最优路径
  - 可以开始路径演示

### 2. 💾 Save Button (保存按钮) - **新功能**
- **功能**: 自动保存当前迷宫为JSON格式
- **操作**: 点击"保存"按钮
- **结果**:
  - 将当前迷宫保存为 `saves/maze_save_时间戳.json`
  - JSON格式符合您要求的标准格式
  - 包含完整的路径信息

### 3. 📂 Load Button (加载按钮) - **新功能**
- **功能**: 加载样例迷宫并生成路径
- **操作**: 点击"加载"按钮
- **行为逻辑**:
  1. **优先加载**: `saves/sample.json` 文件（如果存在）
  2. **自动生成路径**: 加载后自动计算最优路径
  3. **备选方案**: 如果 sample.json 不存在，打开存档选择界面

## 🎯 JSON格式标准

生成的JSON文件严格按照您的要求格式：

```json
{
  "maze": [
    ["#", "#", "#", "#", "#", "#", "#", "#", "#", "#"],
    ["#", "S", "#", " ", "#", " ", "#", " ", "#", "#"],
    ["#", " ", "#", " ", "#", " ", "#", " ", "#", "#"],
    ["#", " ", " ", " ", " ", " ", " ", " ", "E", "#"],
    ["#", "T", "#", "G", "#", "L", "#", "B", "#", "#"],
    ["#", "#", "#", "#", "#", "#", "#", "#", "#", "#"]
  ],
  "metadata": {
    "save_name": "maze_save_20250630_120000",
    "save_time": "2025-06-30T12:00:00",
    "maze_size": 10,
    "path_length": 25
  },
  "path_data": {
    "full_path": [[1,1], [2,1], [3,1], ...],
    "current_step": 0,
    "is_path_complete": false
  }
}
```

## 🎮 元素映射

| 内部代码 | JSON显示 | 说明 |
|---------|---------|------|
| `'1'` | `'#'` | 墙壁 |
| `'0'` | `' '` | 通路 |
| `'s'` | `'S'` | 起点 |
| `'e'` | `'E'` | 终点 |
| `'g数字'` | `'G'` | 金币 |
| `'t数字'` | `'T'` | 陷阱 |
| `'l数字'` | `'L'` | 机关 |
| `'b数字'` | `'B'` | BOSS |

## ⌨️ 快捷键和操作

### 游戏主界面
- **Ctrl+S**: 保存为JSON格式
- **Shift+S**: 保存为CSV格式（兼容旧版本）
- **Ctrl+L**: 打开存档选择界面
- **空格键**: 路径下一步
- **R键**: 重置路径
- **A键**: 自动播放路径

### 存档选择界面
- **↑↓方向键**: 选择存档
- **回车键**: 加载选中的存档并生成路径
- **鼠标双击**: 直接加载存档并生成路径
- **Delete键**: 删除选中的存档
- **N键**: 新建存档
- **ESC键**: 关闭存档界面

## 📁 文件结构

```
saves/
├── sample.json          # 样例迷宫文件（Load按钮优先加载）
├── maze_save_时间戳.json # Save按钮生成的存档
└── *.csv               # 旧格式存档文件
```

## 🔄 使用流程

1. **生成新迷宫**: 点击 Start → 自动生成迷宫和路径
2. **保存当前迷宫**: 点击 Save → 保存为JSON格式
3. **加载样例迷宫**: 点击 Load → 加载sample.json并生成路径
4. **演示路径**: 使用路径控制按钮或快捷键观看路径演示

## ✅ 测试验证

所有新功能已通过测试：
- ✅ JSON格式保存功能正常
- ✅ sample.json加载功能正常  
- ✅ 自动路径生成功能正常
- ✅ 格式转换功能正常
- ✅ 向后兼容CSV格式
- ✅ **存档界面加载后自动生成路径** ← 已修复
- ✅ **双击加载功能** ← 新增功能
- ✅ **动态UI布局适应** ← 新修复功能

### UI自适应测试结果
- ✅ 10x10迷宫: 墙壁60px, 显示600px, 按钮位置正确
- ✅ 15x15迷宫: 墙壁53px, 显示795px, 按钮位置正确
- ✅ 20x20迷宫: 墙壁40px, 显示800px, 按钮位置正确
- ✅ 25x25迷宫: 墙壁32px, 显示800px, 按钮位置正确
- ✅ 加载不同存档: UI自动调整布局

## 🔧 问题修复

### 修复了存档界面加载问题
之前通过 Ctrl+L 选择存档读取时，地图能够加载但没有生成路径。现在已修复：

1. **键盘回车加载**: 选中存档后按回车键，自动加载并生成路径
2. **鼠标双击加载**: 双击存档项，直接加载并生成路径
3. **自动路径生成**: 无论通过哪种方式加载，都会自动重新计算最优路径

### 修复了UI布局自适应问题 ← 新修复
之前加载不同大小的地图时，UI布局会出现问题。现在已修复：

1. **动态尺寸计算**: 根据地图大小自动计算合适的显示尺寸
2. **智能墙壁缩放**: 自动调整墙壁大小，确保地图不会太大或太小
3. **按钮位置自适应**: 所有按钮和控制面板会根据地图大小自动调整位置
4. **实时布局更新**: 当加载不同大小的地图时，UI会立即重新布局

#### 技术特性
- **最小墙壁尺寸**: 20像素（确保可视性）
- **最大墙壁尺寸**: 60像素（防止过大）
- **最大显示尺寸**: 800像素或窗口宽度减去400像素（为控制面板留空间）
- **智能缩放算法**: 根据地图大小自动选择最佳显示参数

现在您的迷宫游戏完全支持您要求的JSON存档格式！

## 🔄 历史迭代展示功能 - **全新功能**

### 功能概述
在随机生成迷宫时，系统会记录每一步生成过程，用户可以回放查看迷宫的构建历史。

### 操作说明

#### 历史模式切换
- **按钮**: `历史模式` / `路径模式` 切换按钮
- **快捷键**: `H` 键
- **功能**: 在历史展示模式和路径展示模式之间切换

#### 历史控制按钮 (仅在历史模式下显示)
- **上一步**: 查看上一个生成步骤
- **下一步**: 查看下一个生成步骤  
- **自动播放**: 自动播放生成历史动画
- **快捷键**:
  - `←` 左箭头: 历史上一步
  - `→` 右箭头: 历史下一步
  - `P` 键: 历史自动播放切换

#### 重要特性
1. **生成时记录**: 只有随机生成的迷宫才有历史记录
2. **读档时无历史**: 从文件加载的迷宫不展示历史过程
3. **状态隔离**: 每次生成新迷宫时会清除之前的历史数据
4. **双模式**: 支持历史演示和路径演示两种独立模式

### 使用场景
- 🎓 **教学演示**: 展示迷宫生成算法的工作过程
- 🔍 **调试分析**: 了解递归分割算法的每个步骤
- 🎮 **娱乐观赏**: 观看迷宫"生长"的动画效果

## 🔧 修复内容

### 多次生成迷宫的状态重置修复
- **问题**: 连续点击Start按钮时，之前的历史数据没有正确清除
- **修复**: 
  - 在 `MazeGenerator.generate()` 中添加历史数据清除
  - 在 `Maze.generate()` 中使用 `reset_all_states()` 方法
  - 确保每次生成新迷宫时所有相关状态都被正确重置
- **验证**: 通过专门的测试脚本确保多次生成不会有数据累加问题

### 状态管理优化
- **新增方法**: `Maze.reset_all_states()` - 统一重置所有状态
- **改进逻辑**: 确保历史模式、路径模式、自动播放等状态的正确切换
- **内存管理**: 避免历史数据在多次生成时累积导致内存问题

## 🛡️ 迷宫边界自动修复功能 - **新增安全特性**

### 功能概述
自动检测和修复迷宫文件中边界不完整的问题，确保算法正常运行。

### 问题背景
某些迷宫JSON文件可能存在边界不是墙壁的情况（如边界包含起点S、终点E或空格），这会导致路径算法报错。

### 自动修复机制

#### 检测规则
系统在加载迷宫时自动检查：
- **上边界**: 第一行是否全是墙壁('#' 或 '1')
- **下边界**: 最后一行是否全是墙壁
- **左边界**: 每行第一列是否全是墙壁  
- **右边界**: 每行最后一列是否全是墙壁

#### 修复动作
当检测到边界问题时：
1. **自动添加边界**: 在原迷宫四周添加一圈墙壁('#')
2. **尺寸调整**: 迷宫尺寸从NxN变为(N+2)x(N+2)
3. **坐标调整**: 如果有路径数据，自动调整坐标(+1,+1)
4. **日志输出**: 显示修复过程和结果

#### 示例
```
原始迷宫 (15x15):
["#","#","#","S","#",...] <- 边界有起点S
...
["#","#","#","E","#",...] <- 边界有终点E

修复后迷宫 (17x17):
["#","#","#","#","#",...] <- 全部墙壁
["#","#","#","S","#",...] <- 原内容向内偏移
...
["#","#","#","E","#",...] 
["#","#","#","#","#",...] <- 全部墙壁
```

### 支持范围
- ✅ **JSON格式**: 完全支持，包括路径坐标调整
- ✅ **CSV格式**: 完全支持，路径自动适配
- ✅ **路径数据**: 自动调整坐标以适应新边界
- ✅ **兼容性**: 对正常迷宫无影响

### 使用场景
- 📂 **导入外部迷宫**: 安全加载来源不明的迷宫文件
- 🔧 **修复损坏文件**: 自动处理格式不标准的迷宫
- 🛡️ **算法保护**: 防止边界问题导致的程序崩溃
- 🔄 **自动化处理**: 无需手动修改文件，系统自动处理

## 🐛 路径生成边界检查修复 - **重要错误修复**

### 问题描述
当加载边界不完整的迷宫文件（如`maze_15_15_2.json`）时，系统会自动添加边界墙壁，迷宫尺寸从15x15变为17x17。但是`SourceCollector`在进行路径搜索时会出现数组越界错误：
```
IndexError: list index out of range
```

### 根本原因
1. **边界检查逻辑错误**: `SourceCollector.outofmap()`方法使用了错误的边界条件（`>` 而不是 `>=`）
2. **网格覆盖问题**: 在重新生成路径后，代码错误地将显示网格重置为原始网格，覆盖了包含路径信息的网格
3. **重复路径生成**: 即使已经有路径信息，系统仍然会强制重新生成路径

### 修复内容

#### 1. SourceCollector边界检查修复
```python
# 修复前（错误）
def outofmap(self,x,y):
    return x < 0 or y < 0 or x > self.rowNums or y > self.colNums

# 修复后（正确）  
def outofmap(self,x,y):
    return x < 0 or y < 0 or x >= self.rowNums or y >= self.colNums
```

#### 2. 智能路径生成逻辑
- **条件检查**: 只在`len(maze.full_path) == 0`时才重新生成路径
- **网格保护**: 不再重置显示网格，保持加载的包含路径信息的网格
- **一致性优化**: 在`main.py`和`save_ui.py`中统一处理逻辑

#### 3. 多处修复点
- ✅ **main.py**: Load按钮逻辑优化
- ✅ **save_ui.py**: 存档界面回车键和双击加载逻辑修复
- ✅ **SourceCollector.py**: 边界检查条件修正

### 测试验证
通过全面测试确认修复效果：
- ✅ **边界检查**: 所有边界条件测试通过
- ✅ **小迷宫测试**: 5x5测试迷宫路径生成正常
- ✅ **直接测试**: `SourceCollector`直接加载修复后迷宫正常
- ✅ **完整流程**: `maze.load_game()`完整流程测试通过
- ✅ **路径长度**: 修复后能正确生成15步路径

### 实际效果
对于`maze_15_15_2.json`文件：
- **修复前**: 加载时报`IndexError`，程序崩溃
- **修复后**: 自动边界修复(15x15→17x17)，成功生成15步路径，程序稳定运行

### 兼容性保证
- ✅ **正常文件**: 对边界完整的迷宫文件无影响
- ✅ **路径保持**: 已有路径信息的文件保持路径不变
- ✅ **格式支持**: JSON和CSV格式都支持边界修复和路径生成