仙境飞剑阵：失落剑谱

项目	内容
这个作业属于哪个课程	H202601软件工程与软件工程实践
这个作业要求在哪里	2026 秋软件工程个人作业（第二次）
这个作业的目标	使用 Python 和 AIGC 完成“一箭又一箭”小游戏
学号	102402151
GitHub 仓库	Fairy-Sword-Array

🎮 在线试玩：仙境飞剑阵：失落剑谱

温馨提示：该网址只能用浏览器打开。作业主体为 Python 独立开发；网页版是为方便在线体验额外制作的展示版本。

一、项目展示

1. 开始界面

开始界面展示游戏标题、副标题、玩法说明、版权信息。点击任意位置进入游戏。

2. 游戏界面

游戏界面包含：

• 当前重天名称与进度；
• 6×6 棋盘；
• 剩余飞剑数量；
• 破阵进度；
• 剑意值，即剩余失误次数；
• 重新开始提示：按 R 重开本重天；
• 飞剑飞行、阵眼解除、粒子拖尾等动画。

3. 通关界面

解除全部阵眼并放尽所有飞剑后，显示“剑阵已破”，随后进入下一重天。

4. 失误界面

单次失误时，剑意值减少 1，界面短暂显示“失误”提示与剑光逸散效果，随后回到当前重天继续。若剑意值归零，则进入失败界面。

5. 失败界面

失误次数耗尽或剑困阵中时，显示失败原因，点击后重新开始。

6. 全部通关界面

所有重天全部通关后，界面显示“九天剑主 失落剑谱终得圆满·点击再入仙境”。点击可返回开始界面。

---

二、项目介绍

1. 游戏名称

《仙境飞剑阵：失落剑谱》

2. 游戏类型

东方仙侠 + 休闲解谜 + 阵法策略 + 视觉沉浸小游戏。

3. 核心规则

• 棋盘为 6×6 网格；
• 每个飞剑具有上、下、左、右四个方向之一；
• 玩家点击飞剑，飞剑沿当前方向直线飞行；
• 若前方没有其他待发飞剑阻挡，飞剑飞出棋盘并消失；
• 若前方存在其他待发飞剑，飞剑被阻挡，不能消失；
• 被阻挡时消耗 1 点剑意，即失误次数；
• 飞剑经过阵眼时，阵眼被解除；
• 解除全部阵眼并放尽全部飞剑后，本关通关；
• 剑意耗尽或所有剩余飞剑都无路可走时，本关失败；
• 游戏中按 R 可重开当前关卡。

4. 与基础“一箭又一箭”的关系

基础作业要求是：点击箭头，判断前方是否有阻挡，无阻挡则飞出，有阻挡则碰撞并扣失误，清空全部箭头通关。

本项目保留了该核心逻辑，并做了仙侠化扩展：

• 箭头 → 飞剑；
• 消除箭头 → 飞剑离场；
• 碰撞反馈 → 震剑、红闪、粒子、音效；
• 关卡 → 九重天；
• 额外加入阵眼机制，使“飞剑经过的路径”也参与解谜。

5. 界面设计

界面采用青蓝、玉绿、金色为主的东方仙侠配色。背景为夜空云海、月亮、飘云与花瓣粒子。棋盘为玉石阵台，飞剑具有剑气拖尾、残像、光晕等表现。

---

三、实现思路

1. 棋盘与方向表示

棋盘使用行列坐标 (row, col) 表示。方向使用字符串：

VEC = {
    "up": (0, -1),
    "down": (0, 1),
    "left": (-1, 0),
    "right": (1, 0),
}

但在棋盘格子移动中，行对应纵向，列对应横向，因此使用：

GRID_VEC = {
    "up": (-1, 0),
    "down": (1, 0),
    "left": (0, -1),
    "right": (0, 1),
}

飞剑类 Sword 保存：

• row、col：所在格子；
• direction：朝向；
• state：idle / fly / blocked / gone；
• plan：飞行路径；
• target：当前目标点。

2. 路径检测

路径检测是核心逻辑。实现为纯函数 trace_path：

def trace_path(row, col, direction, occupied):
    dr, dc = GRID_VEC[direction]
    path = [(row, col)]
    r, c = row, col
    while True:
        nr, nc = r + dr, c + dc
        if not inside(nr, nc):
            return False, path          # 飞出棋盘，畅通
        if occupied(nr, nc):
            return True, path           # 被其他飞剑挡住
        r, c = nr, nc
        path.append((r, c))

其中 occupied(r, c) 由棋盘提供，用于判断该格是否停有其他待发飞剑。

点击飞剑时：

blocked, plan = self.trace_sword(s)
if blocked:
    s.trigger_blocked()
    self.mistakes += 1
    return "blocked"
s.launch(plan, self._on_sword_reach)
return "hit"

这样点击逻辑与路径检测解耦，也方便测试。

3. 飞出与碰撞

• 飞出：launch 后飞剑进入 fly 状态，沿 plan 逐格飞行；plan 为空后继续向棋盘外飞出一段距离，最后进入 gone。
• 碰撞：trigger_blocked 使飞剑进入 blocked 状态，执行“前冲—弹回—红闪—粒子”的动画，动画结束后回到 idle，但失误次数已经增加。

4. 关卡表示

关卡集中在 config.py 的 LEVELS 列表中：

{
    "name": "第一重天 · 云海入口",
    "swords": [
        (2, 2, "up"),
        (3, 3, "left"),
        (1, 4, "down"),
        (4, 1, "right"),
    ],
    "eyes": [(0, 2), (3, 0), (5, 4), (4, 5)],
}

每个关卡包含：

• swords：飞剑位置与方向；
• eyes：阵眼位置；
• name：关卡名。

项目共设计九重天，难度逐步提升。

5. 通关与失败判定

通关条件：

def is_cleared(self):
    eyes_ok = bool(self.eyes) and all(self.eyes.values())
    return eyes_ok and all(s.state == "gone" for s in self.swords)

失败条件：

• 失误次数 mistakes >= MAX_MISTAKE；
• 或进入困阵：没有飞剑在飞、未通关，且所有待发飞剑都无路可走。

6. 重新开始

• 游戏中按 R：调用 restart_current()，恢复本关飞剑、阵眼、失误次数；
• 失败或通关后点击：重新开始或进入下一关。

---

四、AIGC 使用过程

在开发《仙境飞剑阵》的过程中，我主要借助 AIGC 工具完成了核心逻辑优化、动画重构和状态管理。以下记录了 3 次具有代表性的 AIGC 使用过程。

子任务	借助何种 AIGC 技术	AI 实现或提供了什么	效果如何	人工修改
点击空白格逻辑优化	Trae（Agent 模式）	识别出 board.py 中的 handle_click 逻辑缺陷，删除了点击空白格 mistakes += 1 的扣血代码，改为返回 "ignore"；同步修改 game.py 音效播放条件、audio.py 注释及 test_flow.py 测试断言。	一次性完成 4 个文件的联动修改（+7 -14），测试全部通过，成功实现“只有点击前方有阻挡、无法正常飞出的剑才扣血”。	无。Trae 以 Agent 模式自动完成了多文件修改并自测，人工仅确认逻辑与预期一致。
飞剑逐格飞行动画与阵眼解除	DeepSeek（对话式大语言模型）	提供“飞剑逐格飞行 + 拖尾 + 阵眼解除 + 粒子效果”的 Pygame 重构方案。包含 FlyingSword 动画对象设计、dt 驱动逐格插值、边界与其他飞剑碰撞停止、按路径顺序解除阵眼并触发粒子特效的完整代码。	给出了结构清晰的架构方案和可直接参考的代码，实现了逻辑与渲染分离，解决了瞬移和判定不准确的问题。	将代码集成到现有项目架构中，根据实际游戏手感微调了 self.speed（移动速度）和粒子生成数量。
按 R 重开与自适应布局重构	DeepSeek（对话式大语言模型）	提供“布局、关卡状态、动画对象”三者分离的重构方案。设计 Layout 类负责棋盘居中与坐标转换；设计 GameState 类集中管理状态并提供 reset()；改用逻辑浮点坐标解决缩放错位。	实现了按 R 一键重置本重天，6×6 棋盘在不同窗口尺寸下保持正方形居中，动画在缩放时不再错位。	将 Layout 和 GameState 接入现有主循环；根据实际窗口比例调整了 top 和 bottom 边距参数；确认了键盘 R 事件与 state.reset() 的绑定。

截图 1：Trae Agent 模式修改“点击空白格不扣血”逻辑

截图 2：DeepSeek 提供“飞剑逐格飞行与粒子效果”重构方案

截图 3：DeepSeek 提供“按R重开与自适应布局”重构方案

五、测试结果

1. 手工测试

编号	测试内容	预期结果	实际结果	是否通过
T01	点击前方无阻挡的箭头	箭头飞出棋盘并消失	飞剑进入飞行状态，飞出后消失，剩余数减 1	通过
T02	点击前方有阻挡的箭头	箭头不消失，失误次数减 1	飞剑震动、红闪，回到原位，剑意减少 1	通过
T03	点击位于边缘且朝向棋盘外的箭头	箭头正常消失，不发生越界错误	正常飞出，无越界异常	通过
T04	消除本关全部箭头	显示通关并进入下一关	解除阵眼并放尽飞剑后显示“剑阵已破”，进入下一重天	通过
T05	失误次数耗尽	显示失败并允许重新开始	显示“剑阵反噬”，点击后重新开始	通过
T06	游戏进行中重新开始	箭头布局和失误次数恢复	按 R 后本关复原，失误归零	通过

2. 自动化测试

项目包含 test_flow.py，运行：

python test_flow.py

测试内容包括：

• 九重天布局是否合法；
• 剑格是否唯一；
• 阵眼是否与剑格重叠；
• 对向飞剑是否互相阻挡；
• 点空是否不扣剑意；
• 剑意耗尽是否判负；
• 重开本重天是否复原；
• DFS 求解九关是否可零失误通关。

测试输出示例：

== 布局与机制测试 ==
  [OK] 全部 9 重天布局合法
  [OK] 前方有剑阻拦 → 失一点剑意，飞剑不离场
  [OK] 点空 → 不扣剑意
  [OK] 剑意耗尽 3 点 → 剑阵反噬
  [OK] 重开本重天 → 剑意复原，飞剑与阵眼归位

== 九重关可解性与实机通关测试 ==
L1 第一重天 · 云海入口: 破阵  放剑 4/4 · 失误 0 · 阵眼 4/4
...
九重仙境，尽皆可破。

---

六、PSP 表格

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

---

七、安装与运行

1. 开发环境

• Python 3.14
• Pygame

2. 安装依赖

pip install pygame

3. 运行游戏

python main.py

4. 操作说明

• 鼠标点击飞剑：释放飞剑；
• 游戏中按 R：重开当前重天；
• F11：全屏 / 窗口切换；
• 失败或通关后点击：重新开始或进入下一关。

5. 资源说明

音效与音乐放在 assets/sounds/ 与 assets/music/ 下。文件缺失时程序会静默跳过，不影响运行。

---

八、心得体会

这是我第一次严肃的做游戏，整体来说我很满意。不管是画面表现、音乐音效，还是游戏机制，都符合我的预期。其中音乐音效是我精挑细选的。

这次项目让我体会到，AIGC 可以显著提高开发效率，尤其是在生成基础框架、动画思路、测试用例方面。但 AI 生成的代码不能直接无脑使用，尤其是路径检测、边界处理、关卡可解性这些核心逻辑，必须自己理解并验证。

例如方向向量与行列坐标的对应关系，如果写错，表现就是“看起来能跑，但点击后飞剑往错误方向飞”。再比如关卡设计，AI 可以生成布局，但不能保证每关都有解。因此我加入了 DFS 求解测试，确保九重天都能在零失误条件下通关。

最后，再次附上：

🎮 在线试玩：仙境飞剑阵：失落剑谱

感谢试玩！！！