软件工程第二次个人作业——利用 AIGC 完成「一箭又一箭」小游戏

作业信息

项目 内容
这个作业属于哪个课程 https://edu.cnblogs.com/campus/fzu/2026-01SoftwareEngineeringandSoftwareEngineeringPractice
这个作业要求在哪里 https://edu.cnblogs.com/campus/fzu/2026-01SoftwareEngineeringandSoftwareEngineeringPractice/homework/16718
这个作业的目标 使用 Python 和 AIGC 完成「一箭又一箭」小游戏
学号 052404147
GitHub 仓库 https://github.com/QG-LHZ/arrow-puzzle

1. 项目展示

游戏运行截图如下（更多见仓库 images/ 目录）：

  • 开始界面与关卡选择：

    start
    select

  • 游戏界面与提示高亮：

    game hint

  • 碰撞反馈与通关界面：

    collision win

  • 失败界面：

    lose

  • 演示动画（一次碰撞 + 完整通关第 1 关）：

    demo

2. 项目介绍

2.1 游戏规则

棋盘上有若干带方向的箭头（上 ↑、下 ↓、左 ←、右 →）。点击某个箭头后，程序检查它前进方向上（同一行或同一列）到棋盘边界之间是否还有其他箭头：

  • 前方无阻挡 → 箭头飞出棋盘并消失；
  • 前方有阻挡 → 箭头不消失，给出晃动、变红和文字提示，并消耗 1 次失误机会。

清空当前关卡全部箭头即进入下一关；失误次数（3 次）耗尽则本关失败，可重新开始。

2.2 界面设计

采用深色主题，界面分为：

  • 开始界面：标题、规则说明、「开始游戏」和「选择关卡」按钮；
  • 关卡选择界面：列出全部关卡；
  • 游戏界面：顶部显示关卡、剩余箭头、用时和失误爱心，中间是棋盘，底部是「撤销 / 提示 / 自动通关 / 重新开始」四个按钮；
  • 通关 / 失败界面：通关界面显示星级评价和用时。

2.3 主要功能

在完成作业基础要求后，我增加了多项扩展功能：

  • 5 个难度递增、均可通关的关卡，支持关卡选择；
  • 飞出动画与碰撞晃动反馈；
  • 撤销上一步、提示下一步、一键自动通关；
  • 计时与通关星级评价、重新开始；
  • 17 项自动化测试。

2.4 关卡难度设计

关卡按箭头数量和阻挡关系逐步增加复杂度，从教学性质的 4 个箭头递增到 22 个箭头：

关卡 箭头数量 棋盘大小 设计定位
第 1 关 4 4×4 教学关，熟悉规则
第 2 关 8 5×5 两条独立的箭头链
第 3 关 10 5×5 三条链交错，需要观察顺序
第 4 关 16 5×5 环形框架，阻挡关系明显增多
第 5 关 22 6×6 大框架加中间竖列，最终挑战

所有关卡在加入游戏前都通过回溯求解器 find_order 验证，确保至少存在一种完整的消除顺序；同时我对每一关进行了人工试玩，确认交互和动画表现正常。

3. 开发环境

项目 环境
操作系统 Windows 11
Python 3.13
图形界面库 Pygame 2.6.1
开发工具 PyCharm
版本控制 Git + GitHub
测试方式 自编写断言脚本（test_game.py）

4. 实现思路

4.1 箭头与方向的表示

方向统一用一个 (行偏移, 列偏移) 元组表示，天然地和网格坐标对应：

UP = (-1, 0)      # 向上：行号减 1
DOWN = (1, 0)     # 向下：行号加 1
LEFT = (0, -1)    # 向左：列号减 1
RIGHT = (0, 1)    # 向右：列号加 1

4.2 关卡的表示

每个关卡用一个字符串二维列表表示，字符 ^ v < > 对应四个方向，. 表示空格。这样关卡可读性高、便于手工设计和修改。例如第 1 关：

LEVELS = [[
    ">..^",
    "....",
    "....",
    "v.<.",
]]

解析时把字符串转换成 (r, c) -> 方向或空 的二维列表。

4.3 路径检测（核心算法）

路径检测是本游戏最核心的一段。判断某箭头能否飞出，就是看它面朝方向、到棋盘边界之间有没有别的箭头：

def is_path_clear(board, r, c, rows, cols):
    dr, dc = board[r][c]          # 取出该箭头的方向
    cr, cc = r + dr, c + dc       # 从相邻格开始探测
    while 0 <= cr < rows and 0 <= cc < cols:  # 还在棋盘内
        if board[cr][cc] is not None:          # 遇到任意一个箭头
            return False                        # 被阻挡
        cr += dr
        cc += dc
    return True                     # 走到棋盘外都没遇到，前方畅通

关键点：

  • while 的循环条件 0 <= cr < rows and 0 <= cc < cols 天然处理了边界，走到棋盘外循环自动结束，返回 True——这就覆盖了「位于边缘且朝棋盘外」的越界情况；
  • 阻挡条件只看「同一行或同一列」逐格前进，无论这个箭头本身朝哪个方向，只要占着格子就算阻挡，与作业要求一致。

4.4 动画与反馈

  • 飞出：点击可消除的箭头后先把它从棋盘移除，再记录一条「飞出」动画，用 进度² 的加速插值让箭头沿方向滑出棋盘；
  • 碰撞：用垂直方向的「衰减正弦」做晃动，同时变红并显示「碰撞！路径被阻挡」。

4.5 扩展功能

  • 撤销：用操作历史栈记录每一步，还原消除的箭头 / 还回扣除的失误；
  • 提示：扫描棋盘返回一个当前可安全消除的箭头并高亮；
  • 自动通关：复用回溯求解器 find_order，从当前棋盘搜索完整消除顺序后逐步演示；
  • 计时与星级：通关时按剩余失误次数评定 1~3 星，并显示用时。

5. AIGC 使用过程

以下记录基于本次使用 Trae 的真实开发过程整理。开发过程中，我通过多轮对话逐步完善游戏功能，AI 生成的代码经过我的测试、修改和整合后进入项目。

子任务 借助何种 AIGC 技术 AI 实现或提供了什么 效果如何 人工修改
路径检测 Trae 生成四个方向的路径检测代码，并用 (行偏移, 列偏移) 表示方向 逻辑正确，通过 T01~T03 补充了「边缘箭头朝棋盘外」的测试用例，复核边界条件
关卡设计 Trae 生成关卡数组，并写了一个回溯求解器 find_order 验证可解性 5 个关卡全部验证可通关，难度递增 试玩并调整布局，让难度与箭头数递增
碰撞与飞出动画 Trae 实现飞出「加速插值」动画和碰撞「衰减正弦晃动 + 变红」反馈 基本可用，视觉反馈明显 调整晃动幅度和动画时长，让反馈更自然
测试与扩展功能 Trae 生成 T01~T06 自动化测试，并实现撤销、提示、自动通关、计时星级 17 项测试全部通过 修复测试中一处越界笔误，确认撤销 / 提示逻辑与界面交互一致

6. 测试结果

采用自动化测试（python test_game.py）为主，手工试玩为辅。
image

自动化测试运行结果：

[PASS] T01 点击前方无阻挡的箭头
[PASS] T02 点击前方有阻挡的箭头
[PASS] T03 边缘朝向棋盘外不越界
[PASS] T04 消除全部箭头后通关
[PASS] T05 失误次数耗尽后失败
[PASS] T06 重新开始恢复状态
[PASS] 撤销还原已消除的箭头
[PASS] 撤销还原被扣除的失误
[PASS] 提示返回可消除的箭头
[PASS] 部分棋盘仍可求解
[PASS] 关卡 1 存在通关顺序
[PASS] 关卡 2 存在通关顺序
[PASS] 关卡 3 存在通关顺序
[PASS] 关卡 4 存在通关顺序
[PASS] 关卡 5 存在通关顺序
[PASS] 渲染冒烟测试（最后一关完整通关）
[PASS] 自动通关冒烟测试

共 17 通过，0 失败
编号 测试内容 预期结果 实际结果 是否通过
T01 点击前方无阻挡的箭头 箭头飞出棋盘并消失 箭头消失，剩余数减 1 通过
T02 点击前方有阻挡的箭头 箭头不消失，失误次数减 1 箭头保留，失误 3→2 通过
T03 点击边缘且朝向棋盘外的箭头 正常消失，不越界 上/左/右三个方向均正常消失 通过
T04 消除本关全部箭头 显示通关并进入下一关 通关标志置位，场景切换 通过
T05 失误次数耗尽 显示失败并允许重新开始 失误归零后置失败标志 通过
T06 游戏进行中重新开始 布局和失误次数恢复 布局与失误次数均复原 通过
附加 撤销 / 提示 / 自动通关 各自功能正确 17 项自动化测试全部通过 通过

7. Git 提交记录

开发过程中，我按照功能实现的阶段进行了多次提交，而不是在截止前一次性上传整个项目。每完成一个相对独立、可验证的功能，先运行或测试确认当前版本可用后再提交。
00a4972ed810bb732d3752936f9255ee

本项目共 7 次 Commit：

dd4efe1 merge: 合并远程初始提交
ba022af docs: 游戏截图与演示素材
05432c5 test: 自动化测试用例
9dc085d feat: 图形界面与交互实现
4c5160e feat: 基础游戏逻辑与关卡数据
2a57f98 docs: 项目说明与忽略规则
dee5bb2 Initial commit

提交过程基本对应了项目从「项目说明 → 核心逻辑 → 图形界面 → 自动化测试 → 展示素材」的开发顺序。通过 Git 的版本管理，可以清楚地看到每个阶段完成的主要工作，也方便在出现问题时回看不同版本之间的代码变化。

GitHub 仓库地址：https://github.com/QG-LHZ/arrow-puzzle

8. PSP 表格

预估耗时基于我对各任务难度的初步判断，实际耗时为开发过程中的真实记录。

任务 预估耗时（小时） 实际耗时（小时） 差异（小时）
需求分析与游戏设计 1 0.5 -0.5
Python 与图形库学习 2 1 -1
游戏界面实现 3 4 +1
路径与碰撞逻辑实现 2 1.5 -0.5
关卡设计 1.5 1 -0.5
AIGC 辅助开发 2 3 +1
测试与修改 2 2 0
README 与博客撰写 2 1.5 -0.5
合计 15.5 14.5 -1

9. 心得体会

  • AI 带来的帮助：把「箭头 + 方向」抽象成 (行偏移, 列偏移)、用回溯求解器自动验证关卡可解，是我自己容易忽略的角度；AIGC 让我把精力放在规则理解和测试上，而不是重复的界面代码。在界面上，AI 帮我快速搭出了 Pygame 的场景切换和动画框架，省去了大量查文档的时间。
  • 出现的问题：AI 生成的代码在边界条件和细节上仍有疏漏，例如测试里的越界笔误、方法重命名后的调用不匹配，需要逐条运行测试才能发现；AI 给的关卡有时不一定能通关，必须用求解器或试玩验证。此外，AI 生成的动画参数（如晃动幅度、飞出速度）需要反复调整才有较好的手感。
  • 自己的收获：理解了二维网格坐标、方向向量和路径探测的关系；体会到「先写自动化测试、再不断回归」对小型项目同样重要；也认识到 AI 生成的代码必须自己理解、测试并负责。最大的收获是学会了如何给 AI 提清晰的需求——描述越具体，生成的代码越接近可用状态。

10. 素材来源与版权说明

  • 本项目只参考「一箭又一箭」类游戏的基础玩法，没有复制原商业游戏的代码、素材、音效或关卡；
  • 棋盘、箭头、爱心、星星等所有图形均通过 Pygame 绘图 API 在代码中绘制，未使用任何第三方图片素材；
  • 界面文字使用 Windows 系统中文字体渲染；
  • 仓库中不包含密码、Cookie、API Key、Token 等敏感信息；
  • 本项目仅用于课程学习和软件开发实践，不用于商业用途。