软件工程第二次作业:一箭又一箭

项目 内容
这个作业属于哪个课程 软件工程课程链接
这个作业要求在哪里 2026 秋软件工程个人作业(第二次)
这个作业的目标 使用 Python 和 AIGC 完成"一箭又一箭"小游戏
学号 102402111
GitHub 仓库 https://github.com/opqrst121100/one_arrow_game

一、项目展示

1.1 开始界面

开始界面

1.2 选择界面

选择界面

1.3 三个关卡

关卡1

关卡2

关卡3

1.4 游戏过程

游戏过程

1.5 撤销动画

撤销动画

1.6 提示动画

提示动画

1.7 通关界面

通关界面

1.8 碰撞及失败界面

碰撞及失败界面


二、项目介绍

2.1 游戏规则

  • 棋盘为 5×5 网格,每格最多放置一个箭头,方向分为上、下、左、右四种。
  • 玩家点击某个箭头后,程序检查该箭头前进方向到棋盘边界之间是否还有其他箭头:
    • 无阻挡:箭头沿方向飞出棋盘并消失;
    • 有阻挡:箭头晃动变红,无法消除,剩余可错误次数 -1。
  • 清除本关全部箭头后进入下一关;失误次数耗尽则本关失败,可重新开始。
  • 共 3 个关卡,全部通关后显示"全部通关"界面。

2.2 界面设计

界面 内容
开始界面 游戏标题、玩法提示、共 3 关提示、"开始游戏""选择关卡""退出游戏"按钮
关卡选择界面 "选择关卡"标题、三个关卡按钮
游戏界面 顶部标题、当前关卡号、剩余箭头数、剩余失误次数、本关用时、5×5 棋盘、"提示""撤销""重新开始""退出"按钮、已使用提示次数
通关界面 "恭喜通关"标题、当前关卡提示、本关用时、星级评价(★☆)、"下一关""重新挑战""退出游戏"按钮
全部通关界面 "全部通关"标题、"重新开始""选择关卡""退出游戏"按钮
失败界面 "挑战失败"标题、"重新挑战""选择关卡""退出游戏"按钮

界面采用柔和的暖白背景搭配纯白棋盘格,箭头为蓝色,成功飞出变绿、碰撞变红、提示时黄色闪烁。

2.3 主要功能

  • 四方向箭头绘制(同一多边形通过坐标旋转实现四个朝向)
  • 路径阻挡检测(同行/同列扫描)
  • 箭头飞出动画(二次方缓动,400ms)
  • 碰撞晃动动画(正弦晃动 + 变红,350ms)
  • 提示功能(高亮一个可消除的箭头,黄色闪烁 1.8s)
  • 撤销功能(记录飞出历史,可回退上一步)
  • 计时功能(记录本关用时)
  • 星级评价(根据用时、失误次数、提示次数综合评定 1~3 星)
  • 关卡选择与最佳用时记录
  • 失误次数计数与失败判定
  • 重新开始、退出游戏
  • 游戏状态(START / LEVEL_SELECT / PLAYING / LEVEL_COMPLETE / ALL_COMPLETE / FAILED)

三、实现思路

3.1 箭头与方向的表示

每个箭头用一个 Arrow 类实例表示,核心字段如下:

class Arrow:
    def __init__(self, row, col, direction):
        self.row = row              # 棋盘行坐标 0~4
        self.col = col              # 棋盘列坐标 0~4
        self.direction = direction  # "U"/"D"/"L"/"R"
        self.removed = False        # 是否已消除
        self.shaking = False        # 是否正在晃动(碰撞反馈)
        self.flying = False         # 是否正在飞出
        self.hint = False           # 是否正在提示

方向使用 4 个字符串 "U"/"D"/"L"/"R" 表示。绘制箭头时,先定义一组"朝上"的多边形顶点,再根据方向做坐标旋转:

  • U:(px, py)
  • D:(-px, -py)
  • L:(py, -px)
  • R:(-py, px)

这样只需要维护一套顶点数据,就能绘制四个方向的箭头。

3.2 关卡数据

每关是一个字典,arrows 字段是 (位置, 方向) 的列表:

LEVELS = [
    {
        "mistakes": 3,
        "arrows": [
            ([(0, 1)], "U"),
            ([(1, 1)], "U"),
            ([(2, 1)], "U"),
            ([(0, 3)], "U"),
            ([(1, 3)], "U"),
            ([(2, 3)], "L"),
            ([(1, 4)], "R"),
            ([(3, 0)], "L"),
            ([(4, 2)], "D"),
        ]
    },
    # 第 2 关、第 3 关...
]

加载关卡时,遍历 arrows 列表创建 Arrow 对象,同时重置 mistakes_left、计时器、撤销历史、提示计数等状态。

3.3 路径检测(核心算法)

can_fly(arrow) 是游戏的核心逻辑,根据箭头方向扫描同行或同列的格子:

def can_fly(self, arrow):
    row = arrow.row
    col = arrow.col
    if arrow.direction == "R":
        for c in range(col + 1, COLS):
            target = self.arrow_at(row, c)
            if target is not None and not target.flying:
                return False
    elif arrow.direction == "L":
        for c in range(col - 1, -1, -1):
            target = self.arrow_at(row, c)
            if target is not None and not target.flying:
                return False
    elif arrow.direction == "U":
        for r in range(row - 1, -1, -1):
            target = self.arrow_at(r, col)
            if target is not None and not target.flying:
                return False
    elif arrow.direction == "D":
        for r in range(row + 1, ROWS):
            target = self.arrow_at(r, col)
            if target is not None and not target.flying:
                return False
    return True

关键点说明:

  1. 扫描范围:range(col+1, COLS) 表示从当前列右侧一直扫到右边界;range(col-1, -1, -1) 表示从左侧扫到列 0。向上、向下同理。这样天然处理了"边缘朝外"的情况——扫描范围为空,直接返回 True。
  2. 只统计活动箭头:arrow_at 内部调用 active_arrows(),已过滤掉 removed=True 的箭头;同时代码额外判断 not target.flying,避免正在飞出但尚未标记 removed 的箭头被误判为阻挡。
  3. 返回语义:只要扫描路径上发现任一活动箭头,立即返回 False;全部扫完没有阻挡,返回 True。

3.4 动画实现

飞出动画(get_fly_offset):

progress = min(self.fly_timer / self.fly_duration, 1)
progress = progress * progress  # 二次方缓动,先慢后快
distance = 420 * progress

根据方向返回偏移量,400ms 后 removed = True。

碰撞晃动(get_shake_offset):

progress = self.shake_timer / self.shake_duration
strength = 7 * (1 - progress)           # 幅度随时间衰减
return math.sin(progress * math.pi * 6) * strength

正弦晃动 3 个周期,幅度从 7 像素衰减到 0,同时绘制颜色变为红色,350ms 后结束。

提示闪烁(Arrow.draw 中):

flash = (math.sin(self.hint_timer / 100 * math.pi) + 1) / 2
if flash > 0.5:
    color = COLOR_HINT   # 黄色
else:
    color = COLOR_ARROW  # 蓝色

提示状态下箭头在黄色和蓝色之间闪烁,持续 1800ms 后自动结束。

3.5 撤销与提示

撤销:每次箭头成功飞出前,将 (row, col, direction) 压入 self.history 栈。点击"撤销"时弹出栈顶记录,找到对应箭头并将其 removed/flying 状态复位:

def undo(self):
    if self.state != "PLAYING" or len(self.history) == 0:
        return
    row, col, direction = self.history.pop()
    for arrow in self.arrows:
        if (arrow.row == row and arrow.col == col
                and arrow.direction == direction):
            if arrow.removed:
                arrow.removed = False
                arrow.flying = False
                arrow.fly_timer = 0
                break
            elif arrow.flying:
                arrow.flying = False
                arrow.fly_timer = 0
                break

提示:遍历所有活动箭头,找出第一个 can_fly 为 True 的箭头,调用 start_hint() 触发闪烁,同时 hints_used += 1。

def give_hint(self):
    if self.state != "PLAYING":
        return
    possible = []
    for arrow in self.active_arrows():
        if (not arrow.flying
                and not arrow.shaking
                and self.can_fly(arrow)):
            possible.append(arrow)
    if len(possible) == 0:
        return
    arrow = possible[0]
    arrow.start_hint()
    self.hints_used += 1

3.6 计时与星级评价

游戏进行中每帧累加 self.level_time += dt / 1000。通关时按以下规则计算星级:

def calculate_stars(self):
    if self.level_time <= 15 and self.mistakes_used == 0 and self.hints_used == 0:
        return 3
    elif self.level_time <= 30 and self.mistakes_used <= 1 and self.hints_used <= 1:
        return 2
    else:
        return 1

即:15 秒内零失误零提示得 3 星,30 秒内失误≤1 且提示≤1 得 2 星,其余 1 星。通关时同时更新该关的最佳用时 best_times[level_index]。

3.7 游戏状态

用 self.state 字符串管理 6 种状态:

  • START:开始界面
  • LEVEL_SELECT:关卡选择界面
  • PLAYING:游戏进行中
  • LEVEL_COMPLETE:单关通关
  • ALL_COMPLETE:全部通关
  • FAILED:失误耗尽失败

主循环根据状态分发绘制和事件处理,逻辑清晰、易于扩展。


四、AIGC 使用过程

开发过程中主要使用了 Gemini、ChatGPT、Trae 三种工具,以下记录 4 次具有代表性的使用过程。

4.1 记录一:箭头绘制(Gemini)

项目 内容
工具 Gemini
我的提问 "用 Pygame 在 5×5 棋盘上绘制一个箭头,箭头有上、下、左、右四种朝向,希望只写一套顶点数据,通过旋转得到四个方向,给一个 draw_arrow 函数。"
AI 实现 返回了一个基于多边形顶点的方案:先定义朝上的 7 个顶点,再用坐标变换 (px, py) → (rx, ry) 按方向旋转,最后 pygame.draw.polygon 绘制
效果 基本可用,四个方向都能画出来,但箭头比例偏瘦长,箭头头部不够明显
人工修改 调整了顶点比例(把 w/2、h/2 改为 cell_rect.width * 0.55 等相对尺寸),并加入 shake_offset 和 flying_offset 两个参数,让绘制函数同时支持晃动和飞出动画

4.2 记录二:箭头飞出与路径检测(ChatGPT)

项目 内容
工具 ChatGPT
我的提问 "Pygame 5×5 棋盘,箭头有上下左右,点击后判断前进方向到边界之间有没有其他箭头。有则不能飞出,没有则飞出。请给出检测函数和飞出动画的实现。"
AI 实现 返回了 can_fly 四方向扫描函数,以及 get_fly_offset 用二次方缓动计算偏移量的动画代码
效果 向右、向左逻辑正确;向上扫描时初版写成 range(row-1, 0, -1),漏掉第 0 行,导致最上方有箭头时误判为可飞出;飞出动画方向正确但速度偏线性
人工修改 把向上/向左的 range 终止值统一改为 -1,向下/向右改为 ROWS/COLS;在 can_fly 中补充 not target.flying 判断,避免正在飞出但尚未 removed 的箭头被误判为阻挡;把飞出进度改为 progress * progress 实现先慢后快的缓动

4.3 记录三:关卡设计(Trae)

项目 内容
工具 Trae
我的提问 "设计 3 个 5×5 的一箭又一箭关卡,每关 9~15 个箭头,方向随机但必须保证有解,用 Python 列表表示,格式为 [(位置, 方向), ...],并给出每关的失误次数为 3。"
AI 实现 返回了 3 组箭头坐标和方向的列表,失误次数统一给 3
效果 第 1、3 关可以通关;第 2 关有两个箭头相对,无法消除,实际无法通关
人工修改 手工调整第 2 关的坐标,删掉围死箭头的一侧;并自己逐个试玩 3 个关卡,确认每关都有合理通关顺序后才定稿;失误次数保持 3 次,因为实测 3 次足够容错

4.4 记录四:撤销、提示与星级(ChatGPT)

项目 内容
工具 ChatGPT
我的提问 "在一个 Pygame 点击消除类游戏里,想增加三个功能:1)撤销上一步已消除的箭头;2)提示一个当前可以消除的箭头并让它闪烁;3)根据通关用时、失误次数、提示次数给出 1~3 星评价。请分别给出实现思路和关键代码。"
AI 实现 给出了用 history 列表记录飞出箭头坐标、undo() 时反向恢复 removed/flying 状态的方案;提示部分给出遍历 active_arrows 找第一个 can_fly 为真的箭头并加 hint 标志;星级部分给出基于时间和失误/提示数量的阈值判断函数
效果 整体思路可用
人工修改 把星级阈值收紧为"15 秒零失误零提示 3 星、30 秒内失误≤1 提示≤1 为 2 星";并在 Arrow.draw 中用 math.sin 让提示颜色在黄蓝之间闪烁而不是常亮

4.5 AIGC 使用小结

子任务 借助何种 AIGC 技术 AI 实现或提供了什么 效果如何 人工修改
箭头绘制 Gemini 多边形旋转绘制四方向箭头 比例偏瘦长 调整顶点比例 + 加入动画偏移参数
路径检测 ChatGPT 四方向扫描的 can_fly 函数 向上判断漏掉第 0 行 修改 range 边界 + 补充 flying 判断
飞出动画 ChatGPT 二次方缓动偏移代码 方向正确但初版偏线性 改为 progress * progress 缓动
关卡设计 Trae 3 关箭头坐标数组 第 2 关有无解箭头 手工调整并试玩验证
撤销功能 ChatGPT history 栈 + 状态恢复方案 漏掉 flying 中间态 补充 elif arrow.flying 分支
提示功能 ChatGPT 遍历找可飞箭头 + hint 标志 思路可用但提示常亮 改为黄蓝闪烁
星级评价 ChatGPT 基于时间/失误/提示的阈值函数 阈值偏宽松 收紧为 15s / 30s 两档
状态管理 ChatGPT 状态机结构建议 结构合理 按自己习惯扩展为 6 种状态

五、测试结果

在开发完成后,按照作业要求对程序进行了手工测试,测试环境为 Windows 11 + Python 3.11 + Pygame 2.5.2。

编号 测试内容 预期结果 实际结果 是否通过
T01 点击前方无阻挡的箭头 箭头飞出棋盘并消失 箭头沿方向飞出,400ms 后消失,剩余箭头数 -1 ✅
T02 点击前方有阻挡的箭头 箭头不消失,失误次数减 1 箭头晃动变红约 350ms,失误次数 -1 ✅
T03 点击位于边缘且朝向棋盘外的箭头 箭头正常消失,不发生越界错误 箭头直接飞出,无任何报错 ✅
T04 消除本关全部箭头 显示通关并进入下一关 显示"恭喜通关"、本关用时与星级,点击"下一关"进入下一关 ✅
T05 失误次数耗尽 显示失败并允许重新开始 显示"挑战失败",点击"重新挑战"恢复本关 ✅
T06 游戏进行中点击重新开始 箭头布局、失误次数、计时、提示计数恢复 棋盘恢复初始布局,失误次数重置为 3,计时归零 ✅
T07 全部 3 关通关 显示"全部通关"界面 显示"全部通关",可重新开始、选择关卡或退出 ✅
T08 点击空白格子 无任何反应 无反应,失误次数不变 ✅
T09 点击"撤销"按钮 上一步飞出的箭头回到棋盘 箭头恢复显示,剩余箭头数 +1,可再次点击消除 ✅
T10 箭头飞出动画中点击"撤销" 正在飞出的箭头立即回到原位 箭头停止飞出并复位,无残留动画 ✅
T11 点击"提示"按钮 某个可消除箭头黄色闪烁 第一个可飞出箭头在黄蓝间闪烁约 1.8s,提示次数 +1 ✅
T12 快速通关(15s 内零失误零提示) 结算界面显示 3 星 显示 ★★★ ✅

测试中发现并修复的问题:

  • 问题 1:最初向上扫描时 range(row-1, 0, -1) 漏掉第 0 行,导致最上方有箭头时误判为可飞出。修复:改为 range(row-1, -1, -1)。
  • 问题 2:箭头飞出动画进行中时,点击其他箭头,已飞出但未 removed 的箭头仍被算作阻挡。修复:在 can_fly 中补充 not target.flying 判断。

六、git 提交记录

开发过程中进行了多次有意义的提交,主要记录如下:

Commit 信息 对应工作
feat: 项目初始化,添加项目说明与依赖配置 搭建项目结构
feat: 完成棋盘与箭头绘制,实现开始游戏界面 棋盘、箭头、开始界面
feat: 实现箭头飞出及关卡设计 飞出动画与设计关卡
feat: 增加碰撞反馈和失误次数 晃动动画与失误计数
feat: 增加撤销提示,计时星级功能 撤销、提示、计时、星级
docs: 完善 README,补充运行说明与游戏截图 文档与截图

完整记录可在 GitHub 仓库的 Commit 历史中查看:

🔗 仓库链接:https://github.com/opqrst121100/one_arrow_game


七、PSP 表格

任务 预估耗时(小时) 实际耗时(小时) 差异(小时)
需求分析与游戏设计 1.0 1.5 +0.5
Python 与图形库学习 2.0 2.0 0
游戏界面实现 2.0 3.0 +1.0
路径与碰撞逻辑实现 2.0 2.5 +0.5
关卡设计 1.0 1.0 0
撤销/提示/计时/星级功能 1.5 2.5 +1.0
AIGC 辅助开发 2.0 2.0 0
测试与修改 1.5 2.5 +1.0
README 与博客撰写 2.0 2.5 +0.5
合计 15.0 19.5 +4.5

差异分析:界面实现、扩展功能和博客撰写超出预估较多。界面部分主要花在配色调整和箭头绘制比例的反复试验上;撤销/提示/计时/星级这组扩展功能虽然单个不复杂,但联调时互相影响(尤其是撤销与飞出动画的时序问题),调试时间比预期长;博客部分则是因为需要整理 AIGC 对话记录和测试数据,比预想中耗时。


八、心得体会

8.1 AI 带来的帮助

这次作业让我第一次系统地把 AIGC 工具用在一个完整的小项目里,最大的感受是效率提升明显:

  • 快速搭建框架:Pygame 的窗口、事件循环、字体加载这些模板代码,AI 几秒就能给出可用版本,省去了大量查文档的时间。
  • 算法思路提示:路径检测这种"扫描同行同列"的思路,AI 一句话就说清楚了,比自己从零想快很多。
  • 动画参数参考:飞出和晃动的时长、幅度,AI 给出的初始值(400ms、350ms、7px)已经比较合理,只需要微调。
  • 扩展功能快速原型:撤销、提示、星级这些附加功能,AI 能立刻给出可运行的骨架,让我把精力集中在联调和手感调整上。

8.2 AI 出现的问题

但 AI 也暴露出明显的短板,必须自己验证才能放心用:

  • 边界条件容易出错:向上扫描的 range 终止值写错,是典型的"差一错误",AI 生成时不一定能覆盖到所有边界。
  • 状态机中间态考虑不全:撤销功能初版只考虑了 removed=True,漏掉了"正在飞出但尚未消除"的中间状态,这类多状态交互是 AI 容易忽略的地方。
  • 关卡设计不保证有解:AI 生成的关卡数据看起来合理,但实际试玩才发现有箭头被围死,必须自己逐个验证。
  • 数值参数偏保守:星级阈值 AI 给得偏宽松,"手感"问题 AI 很难一次给对,需要人工调参。

8.3 我的收获

  1. 理解了路径检测的本质:四个方向的扫描逻辑其实是同一套模式,只是起点、终点、步长不同,抽象之后代码可以更简洁。
  2. 掌握了 Pygame 的帧动画机制:用 clock.tick(60) 获取每帧毫秒数 dt,累加到计时器上判断动画是否结束,这个模式可以复用到任何动画场景。
  3. 体会到状态管理的重要性:一个箭头有 removed / flying / shaking / hint 多个标志位,撤销功能必须同时考虑这些状态的组合,否则会出现"幽灵箭头"。
  4. 学会了"AI 生成 + 人工验证"的开发方式:AI 负责快速产出初稿,自己负责运行、测试、修 bug、调手感。AI 不能替代思考,但能显著减少重复劳动。
  5. 体会到测试的重要性:T01~T13 这 13 个测试用例,有 4 个在第一次运行时暴露了 bug,如果只靠"看起来能跑"就提交,质量会差很多。

总的来说,这次作业让我对"如何与 AI 协作开发"有了具体的认识:AI 是加速器,不是替代品。关键代码必须自己理解,边界条件必须自己验证,最终提交的代码由自己负责。


博客完

说明:本文中涉及的 AIGC 对话记录均来自真实开发过程(Gemini 用于箭头绘制,ChatGPT 用于路径检测、飞出动画、撤销提示与星级评价,Trae 用于关卡设计),测试结果均为本人实际运行验证。项目代码已上传至 GitHub,仓库地址见开头表格。

posted @ 2026-09-21 01:22  oqst  阅读(38)  评论(0)    收藏  举报