软件工程第二次作业

软件工程第二次作业

这个作业属于哪个课程	软件工程第二次作业
这个作业要求在哪里	软件工程第二次个人作业
这个作业的目标	借助 AIGC 工具完成小游戏开发，同时通过实际运行和测试，对 AI 给出的代码进行判断、修改和完善
学号	102401409
GitHub仓库	一箭又一箭

一、 项目展示

开始界面

游戏过程

• 游戏界面

• 菜单界面

• 错误操作抖动以及重试（重置）界面

• 撤销功能

• 提示功能

• AI求解功能

• 随机关卡

通关界面

二、项目介绍

1. 游戏概述 (Overview)

  本项目是一个基于 Python 和 Pygame 图形库独立开发的休闲解谜类小游戏——“一箭又一箭”。游戏的灵感来源于热门的同名益智玩法，核心在于考验玩家对二维网格空间的观察力、逻辑推理以及对箭头互阻关系的预判能力。

2. 游戏规则与核心玩法 (Game Rules)

• 基础消除：棋盘中分布着四个方向（上、下、左、右）的箭头。玩家点击某个箭头，程序会检测其前进方向到棋盘边界的路径上是否存在其他箭头。
• 路径判定：
  • 若前方无阻挡，该箭头成功飞出棋盘并消除。
  • 若前方存在阻挡，箭头无法消除，触发原地晃动动画，并扣除一次失误机会。
• 胜负机制：在失误次数耗尽前清空盘面所有箭头即为通关；失误次数归零则游戏失败，支持重新挑战或撤销重试。

3. 界面与视觉设计 (Interface Design)

• 多主题渐变：摒弃了单调的纯色背景，采用渐变背景搭配微弱的波点纹理，避免了颜色冲突。
• UI 布局满足要求：
  • 主菜单与关卡选择：提供直观的关卡网格按钮，并在每个按钮下方实时展示历史最高星级与最快通关时间。
  • 黑色半透明托盘：棋盘下方设有沉浸式托盘与圆角边框，UI 控件（菜单、重试、撤销、提示、AI求解）排布紧凑且支持悬停高亮。
  • 箭头形状及颜色：自定义绘制带箭杆的 7 边形多边形箭头，且随机生成颜色。

4. 主要功能与特色 (Key Features & Highlights)

• 本项目在满足基础要求的前提下，实现了多个拓展与工程化功能：
• 多关卡与无限随机模式：
  • 内置 5 个精心设计的固定关卡（从 4x4 到 5x5 进阶难度）。
  • 实现“无限随机模式”：采用逆向时间生成法（Reverse-Time Generation），在后台模拟消除的逆过程随机撒子，从数学原理上100% 保证随机生成的关卡绝对有解。
• 数据持久化与断点续玩：
  • 引入本地 JSON 存档机制，不仅自动记录每关的最高星级与最快用时，还支持中途退出的游戏进度保存。再次打开游戏时可选择“继续游戏”直接接管残局。
• 高级辅助与算法应用（AI 求解）：
  • 撤销（Undo）：利用历史状态栈（Stack）实现任意步数的完美回溯，支持鼠标点击或快捷键 Z。
  • 智能提示（Hint）：自动检索当前可消除的突破口并给予高亮呼吸灯提示（快捷键 H）。
  • DFS 智能求解器：基于人工智能导论中的盲目搜索（深度优先搜索 DFS）算法，在后台毫秒级推演通关路径并支持自动演示播放（快捷键 A）。同时具备反作弊机制：使用过 AI 求解的对局将不计入历史最佳排行榜。

三、实现思路

1. 游戏数据表示设计

为了清晰、高效地管理游戏状态，本项目在数据结构上采用了“逻辑与视图分离”的设计思路：

• 方向表示（Direction）：
  • 使用数字 1、2、3、4 分别代表上、下、左、右四个基本方向。
  • 在代码中通过字典 DIR_MAP 映射为二维网格的行/列偏移量（例如：上 1 对应 (-1, 0)，右 4 对应 (0, 1)），便于通过向量叠加实现位置推演。

    DIR_MAP = {1: (-1, 0), 2: (1, 0), 3: (0, -1), 4: (0, 1)}
    

• 箭头表示（Arrow 类）：
  • 每个箭头对象维护其在矩阵中的逻辑坐标 (r, c)、朝向类型 dir_type、像素渲染坐标 (x, y) 以及动画状态（idle 静止、shaking 碰撞晃动、flying 飞出）。
  • 同时为每个箭头随机赋予鲜艳的填充色，配合暗色背景，确保视觉辨识度。

        def __init__(self, r, c, dir_type):
            self.r, self.c = r, c
            self.dir_type = dir_type
            self.x, self.y = c * GRID_SIZE, r * GRID_SIZE
            self.state = "idle"
            self.shake_timer = 0
            self.speed = 20
            self.is_dead = False
            self.is_hinted = False
            self.color = (random.randint(50, 255), random.randint(50, 255), random.randint(50, 255))
    

• 关卡表示（Level Matrix）：
  • 每个关卡本质上是一个二维数组（List of Lists）。
  • 矩阵中的元素 0 表示空白网格，非零数字（1-4）代表对应方向的箭头。这种设计使得关卡扩展极为方便，只需定义不同的二维矩阵即可实现从 4x4 到 5x5 多样化阵型的扩展。

    LEVELS = [
        {"grid": [[0, 0, 0, 0], [0, 1, 0, 0], [0, 4, 2, 0], [0, 0, 2, 0]], "mistakes": 3, "target_time": 30},
        {"grid": [[0, 1, 0, 2], [4, 4, 1, 0], [0, 1, 0, 0], [0, 3, 1, 2]], "mistakes": 4, "target_time": 45},
        {"grid": [[1, 2, 3, 4], [3, 2, 1, 1], [1, 3, 4, 4], [4, 2, 1, 1]], "mistakes": 5, "target_time": 50},
        {"grid": [[1, 1, 3, 3], [4, 1, 1, 4], [3, 4, 1, 4], [1, 1, 1, 1]], "mistakes": 3, "target_time": 45},
        {"grid": [[0, 1, 1, 1, 0], [3, 4, 1, 4, 4], [3, 3, 1, 2, 4], [3, 1, 3, 2, 4], [0, 2, 2, 2, 0]], "mistakes": 5,
         "target_time": 60}
    ]
    

2. 核心路径检测方法详解（重点）

路径检测是整个游戏算法的灵魂，直接决定了点击箭头时是“成功飞出”还是“受阻扣血”。其核心思想是“射线模拟与障碍扫描”。

具体实现步骤如下：

• 获取方向向量：
  • 当玩家点击网格中的某个箭头时，程序首先获取该箭头的逻辑坐标 (r, c) 及其朝向 dir_type，并通过 DIR_MAP 获取其对应的行偏移 dr 和列偏移 dc。
  • 具体来说，游戏开始后，鼠标点击发生时（处于playing状态），触发Game.run()方法的以下代码：

    ...
    if event.type == pygame.MOUSEBUTTONDOWN and event.button == 1:
    ...
                          elif self.state == "PLAYING":
                            self.handle_playing_click(event.pos)
    ...
    

  • 调用handle_playing_click(event.pos)后，检测到鼠标确实点击了箭头，获得鼠标的x、y坐标，并计算处于哪个方格（亦即箭头的逻辑坐标（r，c）），当这个空格的箭头存在时，调用trigger_arrow(grid_r, grid_c)：

    ...
    mx, my = pos
            grid_c, grid_r = int((mx - self.offset_x) // GRID_SIZE), int((my - self.offset_y) // GRID_SIZE)
            if 0 <= grid_r < self.rows and 0 <= grid_c < self.cols:
                if self.grid[grid_r][grid_c] != 0:
                    self.trigger_arrow(grid_r, grid_c)
    ...
    

  • 调用trigger_arrow(grid_r, grid_c)之后，遍历箭头数组，如果（r，c）坐标恰好对上，并且其状态为“idle”，调用check_path_clear(grid_r, grid_c, arrow.dir_type)，并给出该箭头的朝向（dir_type），根据其返回值决定是否飞出，若飞出，将该位置的网格值置为 0（让出路径），供后续箭头通行：

      ...
                if arrow.r == grid_r and arrow.c == grid_c and arrow.state == "idle":
                    ...
                    if self.check_path_clear(grid_r, grid_c, arrow.dir_type):
                        arrow.state = "flying"
                        self.grid[grid_r][grid_c] = 0
                    ...
      ...
    

  • 在check_path_clear(grid_r, grid_c, arrow.dir_type)中，通过 DIR_MAP 获取其对应的行偏移 dr 和列偏移 dc：

        ...
        dr, dc = DIR_MAP[dir_type]
        ...
    

• 步进式边界与碰撞扫描：
  设计了一个高效的 check_path_clear(r, c, dir_type) 核心函数：
  • 从当前箭头位置的下一个格子开始(curr_r, curr_c)，进入 while 循环沿着该方向向前推进。

    ...
        curr_r, curr_c = r + dr, c + dc
    ...
    

  • 边界条件：循环条件限定 curr_r 和 curr_c 必须在棋盘合法行列范围内(0 <= curr_r < rows 且 0 <= curr_c < cols)。
  • 阻挡判定：在推进的每一步中，检查逻辑网格 grid[curr_r][curr_c]。如果发现该位置的值不等于 0，说明前方存在其他箭头阻挡，函数立即中断并返回 False。

    ...
            while 0 <= curr_r < rows and 0 <= curr_c < cols:
                if grid[curr_r][curr_c] != 0: return False
                curr_r += dr
                curr_c += dc
    ...
    

• 判定结果：
  如果 while 循环顺利执行完毕且没有触发任何阻挡返回，说明该方向直到棋盘边界之间没有任何障碍，函数返回 True。设置此箭头的状态为“flying”，此时主程序将调用Arrow类的update方法，更新被点击的箭头的位置，触发“飞出”动画。

  def run(self):
          while True:
  ...
                  for arrow in self.arrows: arrow.update()
  ...
              self.draw()
  ...
  

• 复用价值：
  这个路径检测函数不仅在玩家每次鼠标点击时被调用，还被巧妙地复用于“智能提示（Hint）”功能以及“AI 深度优先搜索（DFS）自动求解器”中，实现了核心算法的高内聚与高复用。

3. 附加功能介绍

• 基于 DFS 的 AI 自动求解器与反作弊系统
  • 算法原理：没有依赖外部大模型，而是采用了《人工智能导论》中经典的深度优先搜索（DFS）与回溯算法（Backtracking）。AI 启动时，会在后台深拷贝一份当前逻辑网格，通过递归寻找“当前无阻挡箭头 -> 模拟消除 -> 继续深搜”的路径。若遇死锁则回溯恢复状态，直到找到一条清空全盘的完美解序列。（Game.get_solution(self)中的定义的dfs(grid, path)）

            def dfs(grid, path):
                arrows = [(r, c, grid[r][c]) for r in range(self.rows) for c in range(self.cols) if grid[r][c] != 0]
                if not arrows: return path
                valid_moves = [(r, c, d) for (r, c, d) in arrows if self.check_path_clear(r, c, d, grid)]
                if not valid_moves: return None
                for r, c, d in valid_moves:
                    grid[r][c] = 0
                    res = dfs(grid, path + [(r, c)])
                    if res: return res
                    grid[r][c] = d
                return None
    

  • 自动播放与防作弊：寻路成功后，主程序会以固定的时间间隔（pygame.time.get_ticks() 延时控制）接管鼠标，自动播放解局动画。同时引入了“反作弊标记（used_ai）”：一旦玩家在关卡中呼叫了 AI，该局成绩将不计入本地最高分排行榜。

    def start_ai_solver(self):
            if self.is_auto_playing: return 
            self.used_ai = True  
            solution = self.get_solution()
            if solution:
                self.auto_path = solution
                self.is_auto_playing = True
                self.last_auto_move_time = pygame.time.get_ticks()
                for a in self.arrows: a.is_hinted = False
            else:
                self.no_solution_msg_timer = pygame.time.get_ticks() + 3000
    

• 基于“时光倒流”算法的无限随机关卡
  • 设计难点：如果纯粹在网格中随机生成箭头，极易产生“多个箭头互相指着对方”的无解死锁局面。
  • 逆向生成算法：为了 100% 保证随机生成的关卡绝对有解，采用了类似拓扑排序逆向思维的“时光倒流（Reverse-Time Generation）”算法。程序从一个纯空的棋盘开始，每次寻找一个“正前方无阻挡”的空位放置箭头。这相当于模拟玩家消除过程的倒放，最后放置的箭头必然是玩家开局时可以消除的突破口，完美解决了死锁生成问题。

        def init_new_random_level(self):
        …
            while placed < difficulty:
                valid_slots = []
                for r in range(rows):
                    for c in range(cols):
                        if grid[r][c] == 0:
                            for d in [1, 2, 3, 4]:
                                if self.check_path_clear(r, c, d, grid, rows, cols):
                                    valid_slots.append((r, c, d))
                if not valid_slots: break 
    
                r, c, d = random.choice(valid_slots)
                grid[r][c] = d
                placed += 1
        …
    

• 利用历史状态栈（Stack）实现无缝撤销（Undo）
  • 数据结构应用：利用数据结构中的“栈（Stack，后进先出）”来管理历史快照。(Game.save_history())

    state = {
                "mistakes": self.mistakes,
                "grid": [[self.grid[r][c] for c in range(self.cols)] for r in range(self.rows)],
                "arrows": []
    }
    

  • 实现细节：在玩家每次有效点击箭头之前，程序会将当前的“二维网格矩阵、剩余失误次数、所有箭头对象的属性（坐标、朝向、状态）”打包成一个字典，压入 history 列表。按下撤销键时，直接从栈顶 pop() 出上一个状态进行全盘覆盖。这不仅实现了逻辑的回退，连 UI 和计分板也会瞬间回到上一步，是状态机管理在游戏开发中的典型应用。

        def save_history(self):
        …
            for a in self.arrows:
                state["arrows"].append({
                    "r": a.r, "c": a.c, "dir_type": a.dir_type, "x": a.x, "y": a.y,
                    "state": a.state, "is_dead": a.is_dead, "color": list(a.color), "is_hinted": a.is_hinted
                })
            self.history.append(state)
    
        def undo(self):
            if not self.history: return
            last_state = self.history.pop() # 弹出
            
           …    # 获得弹出的状态细节
    
            self.arrows = []
            for a_data in last_state["arrows"]:    # 覆盖
                new_arrow = Arrow(a_data["r"], a_data["c"], a_data["dir_type"])
                new_arrow.x, new_arrow.y = a_data["x"], a_data["y"]
                new_arrow.state, new_arrow.is_dead = a_data["state"], a_data["is_dead"]
                new_arrow.color, new_arrow.is_hinted = tuple(a_data["color"]), a_data["is_hinted"]
                self.arrows.append(new_arrow)
                
            …    # 处理已完全弹出的情况
    

• 游戏进度持久化与断点续玩 (Save & Resume)
  • 分离式存储架构：使用 Python 标准库 json 搭配文件读写操作（os.path），在本地动态生成 save_data.json。数据被划分为 records（各关卡的历史最高星级与最快时间）和 progress（当前未打完的残局快照）两部分。（Game.save_all_data())

    progress = {
                    "level": self.current_level,
                    "mistakes": self.mistakes,
                    "elapsed_time": elapsed,
                    "has_started_moving": self.has_started_moving,
                    "used_ai": self.used_ai,
                    "grid": self.grid,
                    "arrows": [{"r": a.r, "c": a.c, "dir_type": a.dir_type, "color": list(a.color)} for a in self.arrows if not a.is_dead],
                    "history": self.history
                }
    
    data = {"records": self.level_records, "progress": progress}
    

  • 自动拦截与恢复：当玩家在关卡内点击关闭退出时，程序会立即计算当前耗时，并将历史撤销栈、棋盘布局一并序列化存入硬盘。下次启动游戏时，开始界面会自动检测到 progress 数据的存在，并无缝渲染“继续游戏”的恢复分支。
• 智能提示系统（Hint）与呼吸灯特效
  • 逻辑复用：复用了核心的 check_path_clear 路径扫描函数。触发提示时，程序遍历场上所有静止的箭头，挑出一个当前合法的“可消除箭头”，将其 is_hinted 属性设为真。

        def trigger_hint(self):
            valid_arrows = [a for a in self.arrows if a.state == "idle" and self.check_path_clear(a.r, a.c, a.dir_type)]
            if valid_arrows:
                hint_arrow = random.choice(valid_arrows)
                hint_arrow.is_hinted = True
    

  • 视觉渲染：利用 math.sin(pygame.time.get_ticks()) 将时间戳转化为平滑的正弦波，为提示的箭头绘制一个色彩动态交替的“呼吸灯”边框，引导玩家视线。

四、AIGC使用过程

子任务	借助何种 AIGC 技术	AI 实现或提供了什么	效果如何	人工修改
无限随机模式生成	Gemini	提供了“时光倒流（逆向放置）”算法	确保生成的随机关卡 100% 绝对有解,核心逻辑完美，但最初设定的最大生成行数（7行）过大,导致网格挡住了底部的提示文字	发现重叠现象后，修改了 init_new_random_level 函数，将生成的最大行数限制在 4 到 5 行以内，完美留出底部 UI 空间
跨平台UI字体兼容	Gemini	解释了 Pygame 底层引擎对 macOS 彩色 Emoji 支持受限的原因，并提供了纯净版文字渲染代码	解决了 macOS 下出现的渲染空白和乱码豆腐块问题，保证了界面跨平台的一致性	全面移除了相关字符串中的 Emoji 符号，并手工微调了文本的 Y 轴坐标和间距以保持界面平衡
断点续玩与界面调整	Gemini	提供了 JSON 进度序列化存储逻辑，并在主界面生成了圆角矩形的“继续游戏”按钮	存档与恢复逻辑精准，但主界面生成的按钮文本字号（font_large）过大，撑爆了原设定的矩形框	审查代码后，将文本渲染参数从 font_large 修改为 font_normal，并增加了“点击菜单时触发自动存档”的逻辑

需要特别注意的点：

通过本次与 AI 的协作开发，我认识到 AIGC 虽然能快速提供高质量的核心算法（如逆向生成、DFS 求解），但在 UI 布局、多端兼容性以及具体交互细节上，依然需要开发者基于实际运行效果进行人工审查和参数微调。

五、测试结果

编号	测试内容	预期结果	实际结果	是否通过
T01	点击前方无阻挡的箭头	箭头飞出棋盘并消失	箭头平滑飞出屏幕边界，对象被内存正确回收	通过 ✅
T02	点击前方有阻挡的箭头	箭头不消失，失误次数减 1	箭头触发碰撞晃动动画，左上角失误次数成功扣减	通过 ✅
T03	点击位于边缘且朝向棋盘外的箭头	箭头正常消失，不发生越界错误	边界算法判定正常，箭头顺利飞出，终端未报出数组越界异常	通过 ✅
T04	消除本关全部箭头	显示通关并进入下一关	触发结算黑底半透明遮罩，正确计算并显示通关用时与星级，点击进入下一关	通过 ✅
T05	失误次数耗尽	显示失败并允许重新开始	触发 GAME_OVER 红色警告界面，点击屏幕后自动重新加载本关初始状态	通过 ✅
T06	游戏进行中重新开始	箭头布局和失误次数恢复	点击“重试”按钮，网格阵型、倒计时器与失误次数瞬间完美重置	通过 ✅
T07	触发状态回溯 (撤销功能)	游戏状态退回至上一次点击前的状态	历史快照栈（Stack）成功弹出上一帧数据，盘面与计分板无缝回退。	通过 ✅
T08	AI 自动求解与防作弊判定	AI 接管游戏并自动消除，通关成绩作废	DFS 算法成功求解并按 0.2s 间隔播放，结算时触发红字警告且不覆盖本地历史最高分。	通过 ✅
T09	中断游戏与断点续玩	关闭游戏再次打开时，可继承上次未打完的残局	程序成功从本地 JSON 提取 progress 切片，点击“继续游戏”后倒计时无缝衔接。	通过 ✅
T10	无限随机模式防死锁验证	生成 100% 可通关的随机关卡，且 UI 不重叠	逆向时间生成法确保了绝对无死锁，行数限制（4~5行）完美适配了底部提示区。	通过 ✅

六、PSP表格

任务	预估耗时（小时）	实际耗时（小时）	差异（小时）
需求分析与游戏设计	2.0	1.5	-0.5
Python 与图形库学习	3.0	1.0	-2.0
游戏界面实现	3.0	2.0	-1.0
路径与碰撞逻辑实现	4.0	1.5	-2.5
关卡设计	2.0	1.5	-0.5
AIGC 辅助开发	1.0	2.5	+1.5
测试与修改	2.0	1.5	-0.5
README 与博客撰写	1.5	2.0	+0.5
合计	18.5	13.5	-5.0

耗时差异分析：

• 从 PSP 表格可以看出，本项目的实际总耗时（13.5 小时）显著低于最初的预估总耗时（18.5 小时）。这主要归功于 AIGC 技术的深度参与。
• 代码与学习成本锐减：在“Python 与图形库学习”以及“路径与碰撞逻辑实现”阶段，得益于大模型的代码生成与纠错能力，原本需要耗费大量时间查阅 Pygame 文档和调试网格坐标的工序被极大地压缩了。
• AI 沟通成本略微超发：虽然代码产出快，但在“AIGC 辅助开发”这一项上，实际耗时超出了预期。主要原因是前期提示词（Prompt）描述不够精准，以及在处理 macOS 平台专属的 Emoji 字体渲染、UI 元素重叠等细枝末节的问题时，需要反复与 AI 进行多轮对话与微调。
• 总体评价：AI 作为辅助工具，在算法框架搭建（如 DFS 求解、逆向生成算法）上效率惊人，极大地提升了本次软件工程作业的开发体验。

七、心得体会

  作为一名大三计算机科学与技术专业的学生，这次利用 AIGC 辅助完成软件工程项目的经历，对我而言不仅是一次高效的开发实践，更是一次对“开发者”角色定位的深刻重塑。在整个编程的过程中，我有了以下几点深刻的体会：

1. AIGC 带来的巨大帮助

• 学习API的成本下降：以前接触一个新的图形库（如 Pygame），需要耗费大量时间去查阅文档、理解事件循环和双缓冲渲染机制。而这次，AI 直接帮我搭建了标准的游戏主循环框架，让我能将 100% 的精力集中在核心的业务逻辑（路径检测、状态管理）上。
• AI在底层的算法方面的优势：在实现“无限随机关卡”和“AI 自动求解”等附加高阶功能时，AI 提供了极具行业标准的思路。例如，利用《人工智能导论》中经典的 DFS（深度优先搜索）实现求解器，以及巧妙使用“时光倒流（逆向放置）”算法来保证随机关卡绝对有解。这些精妙的算法极大地拔高了项目的上限。

2. 协作中暴露的问题

  在享受高效的同时，我也真实遇到了 AIGC 目前的局限性，这让我意识到人类的代码审查（Code Review）绝对不可或缺：

• 缺少视觉与空间的感知：AI 擅长处理纯逻辑，但缺乏对图形界面的“视觉直觉”。比如在测试中，AI 最初设定的随机关卡行数过多，导致生成的网格直接遮挡了底部的提示文字；另外，在按钮 UI 中，AI 指定的 font_large 字号过大，直接撑爆了设定好的圆角矩形。这些纯视觉的越界问题，最终都需要我手动打断点并调整像素坐标来修复。
• 跨平台兼容性的问题：在 macOS 环境下测试时，我发现 AI 最初在字符串中添加的彩色 Emoji（如 ⭐、❤️）变成了无法渲染的乱码或透明空格。这是因为底层的 SDL_ttf 引擎对某些系统字体的支持存在局限，最终还是通过人工排查并替换回纯文本才得以解决。

3. 自己的成长与收获

• 串联以往学过的知识：这次开发让我对前两年学过的理论课知识有了更深的理解。以前在书本上学的“栈（Stack）”，这次完美应用在了“撤销（Undo）”的历史状态回溯中；课本上的搜索树和图论，变成了肉眼可见的自动解局动画。
• 软件工程思维的建立：通过遵循 PSP 软件开发流程并编写详尽的测试用例，我体会到了“软件工程”与“随便写个脚本”的本质区别。在 AIGC 的加持下，开发者未来的核心竞争力将不再是单纯的“手写代码速度”，而是需求拆解能力、Prompt 表达能力以及对复杂系统的调试与把控能力。