# 2026PythonDZY_Soul Knight Clone_Python Edition

**Repository Path**: withyoghurt/2026-python-dzy_-soul-knight-clone_-python-edition

## Basic Information

- **Project Name**: 2026PythonDZY_Soul Knight Clone_Python Edition
- **Description**: 本项目是一款基于 Python3 和 Pygame 框架开发的Roguelite Top-down Shooter。玩家扮演一名深入地牢的勇士，需要在由程序随机生成的无限迷宫中探索。游戏包含完整的战斗系统（射击/近战切换）、资源管理（弹药/护甲）、角色成长（Buff拾取）以及自动存档系统等系统。目标是生存并清理总计100层的房间，最终挑战胜利。
- **Primary Language**: Python
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-01-24
- **Last Updated**: 2026-01-31

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Python程序设计基础大作业

## 题目：Soul Knight Clone: Python Edition (元气骑士-Python复刻版)

--------------------------

## 0. 写给老师 (To My Professor)

**项目选题原因：之前本人有过基于另一个基于JAVA开发的游戏(Minecraft)的JavaScript(KubeJS)制作新游戏(“整合包”)的独立工程开发经历，本学期在您的课上深入了解了Python这个编程语言之后对其底层的“类”等非常便于游戏开发的语言结构和工具产生了想法，于是决定以复刻《元气骑士》这个相对简单的类Roguelike游戏项目为最终目标，先不论性能和内容丰富度而尽可能去逼近它的功能和基础内容，最终提交版也确实基本实现了它的基础功能和基础内容。**

**项目开发感想与开发过程说明：本项目的设计、架构和调试过程总共长达半个月，期间本人几乎没做任何其他工作，全身心投入到此项目中了，接近提交时间开始准备结项时本人心情真可谓“酣畅淋漓”，因此感谢老师课程的启发。本项目的最底层架构是本人在学习了 Pygame 后纯人工搭建的，后面添加内容和调试在一定程度上借助了大语言模型的帮助。开发期间遇到了贴墙移动无法合理滑行、存档存储算法不合理、各种初始化错误和运行顺序混乱、渲染逻辑过于简单以致游戏运行不流畅、贴图素材预处理和渲染崩溃、怪物交互和行为逻辑错误等等一系列数不胜数的问题，过程真可谓曲折艰辛。最终版本累计载入了9段音频素材和51个图像素材，编写了*约3000行*代码。** 

**项目简阅引导：配好环境后运行main.py启动游戏后，可以先创建一个测试存档操作几下，通关后看到胜利动画并听到音乐，之后看到支持作者页面，然后新建一个正常存档简单游玩体验一下，看看功能的实现情况和内容的表现情况，再粗略阅览一下代码内容，产生基本的评价和评分。**

--------------------------

## 1. 项目名称与简介 (Project Name & Description)

**项目名称：** Soul Knight Clone: Python Edition

**项目简介：**
本项目是一款基于 Python3 和 Pygame 框架开发的 **2D 俯视角随机地牢射击游戏**（Roguelite Top-down Shooter）。玩家扮演一名深入地牢的勇士，需要在由程序随机生成的无限迷宫中探索。游戏包含完整的战斗系统（射击/近战切换）、资源管理（弹药/护甲）、角色成长（Buff拾取）以及自动存档系统等系统。目标是生存并清理总计 **100 层** 的房间，最终挑战胜利。

本项目不依赖复杂的第三方引擎，而是通过 Python 代码底层实现了从地图算法到物理碰撞、从UI渲染到数据持久化的完整游戏引擎逻辑。

---------------------

## 2. 大作业难度等级评定 (Difficulty Assessment)

**自评等级：四星难度 (★★★★)**

根据《大作业难度等级评定标准》，本项目符合 **2.2 四星难度** 中的以下两条标准：

1.  **“使用中型框架实现较为复杂的图形界面”**
    * **理由：** 本项目虽然使用 Pygame 基础库，但独立封装了一套完整的 UI 框架（`ui.py`），实现了包括**动态小地图**、**可拖拽滑动条**、**复选框**、**输入框**以及**多层级菜单系统**（主菜单、设置、存档管理、游戏内HUD）。游戏界面支持实时数据更新（FPS、血量插值动画）和全屏/窗口切换，交互逻辑远超一般简单的 Pygame 练习。

2.  **“综合多种Python应用场景，实现较为复杂的桌面应用程序开发”**
    * **理由：** 本项目不仅仅是一个简单的游戏循环，而是一个架构完整的应用程序，包含：
        * **算法应用：** 在 `tilemap.py` 中实现了 **程序化地图生成算法**，利用随机游走和矩形划分生成不重复的房间与走廊；实现了 **Chunk（分块）预渲染技术**，解决了 400x400 超大地图的渲染性能瓶颈。
        * **数据持久化：** 在 `save_manager.py` 中实现了基于 JSON 的**全状态序列化系统**。不仅能保存玩家属性，还能完整保存随机生成的地图结构、所有敌人/箱子的位置及状态、迷雾探索进度等，支持“即存即玩”和多存档管理。
        * **物理引擎优化：** 在 `sprites.py` 中实现了自定义的**分块物理碰撞检测**，解决了高速物体在网格地图中的“穿墙”和“边缘粘连”问题。

--------------------- 

## 3. 安装 (Installation)

本项目依赖 `pygame` 库。

1.  **环境要求：** Python 3.8 或以上版本，开发所用的环境为Python 3.13.7。
2.  **安装依赖：**
    请在终端或命令行中运行以下命令：
    ```bash
    pip install pygame
    ```
    *(或者直接使用项目根目录下的 requirements.txt)*
    ```bash
    pip install -r requirements.txt
    ```

3.  **运行游戏：**
    确保所有代码文件（`main.py`, `settings.py` 等）和 `resources` 文件夹在同一目录下，运行：
    ```bash
    python main.py
    ```

---------------------

## 4. 使用方法 (Usage)

### 4.1 游戏架构流程
本项目采用 **面向对象编程** 和 **状态机** 设计模式，核心架构如下：

1.  **核心循环 (`main.py`)**：
    * `Game` 类作为总控，维护 `state` 变量（MENU, PLAYING, SETTINGS, MAP, SAVES 等）。
    * 主循环根据当前状态分发 `events()`, `update()`, `draw()` 调用，确保不同界面逻辑解耦。

2.  **地图生成与渲染 (`tilemap.py`)**：
    * 游戏开始时，算法在 400x400 的网格中生成房间和走廊。
    * **Chunk 优化**：将地图切分为 32x32 的区块（Chunk），预先渲染为静态 Surface。游戏运行时仅绘制摄像机视野内的区块，极大降低了 Draw Call，保证了 60 FPS 的流畅度。

3.  **数据管理 (`save_manager.py`)**：
    * 游戏支持自动存档。当玩家进入新房间或点击保存时，`SaveManager` 会将内存对象（Player, Mobs, MapTiles）打包为 JSON 写入 `saves/` 目录。

### 4.2 游戏玩法说明
**通关目标：**
* 玩家需要探索并清理 **100 个房间** (`MAX_ROOMS = 100`)。
* 每进入一个新房间，大门会强制关闭，并生成随机数量的怪物。
* 消灭所有怪物后，房间会掉落补给品（弹药、血包、护甲包）和 **永久强化Buff**（攻击力提升、暴击率提升、护甲上限提升）。
* 到达第 100 个房间并清理完毕后，将触发胜利结局。

**战斗机制：**
* **射击模式：** 按下攻击键发射子弹，消耗弹匣弹药。弹匣耗尽需按 `R` 装填（消耗备弹）。
* **近战模式：** 当弹匣和备弹全部耗尽时，玩家自动切换为近战攻击（无消耗，但距离短，风险高）。
* **死亡机制：** 生命值归零游戏结束。可以在结算界面选择“复活”（记录死亡次数）或返回主菜单。

**测试存档：**
* **创建测试存档：** 在游戏主菜单单击`Loud Saves`,单击所弹出的菜单下方的`New Text Gme`,直接进入生成的测试存档，其内部只有初始房间和最终房间并且及其容易通过，胜利后会弹出通关动画和支持作者页面。
* **近战模式：** 当弹匣和备弹全部耗尽时，玩家自动切换为近战攻击（无消耗，但距离短，风险高）。
* **死亡机制：** 生命值归零游戏结束。可以在结算界面选择“复活”（记录死亡次数）或返回主菜单。

### 4.3 界面 (UI) 详细说明
*![img_1.png](resources/img_1.png)*
*![img_2.png](resources/img_2.png)*

* **左上角 (HUD - 状态栏)：**
    * **绿色条：** 玩家生命值 (Health)。
    * **蓝色条：** 玩家护甲值 (Armor)。护甲受损后可以通过道具恢复，护甲归零前生命值不会受损。
    * **黄色文字：** 弹药量 (当前弹匣 / 剩余备弹)。
    * **红色/橙色文字：** 实时显示的攻击力数值（Damage）和暴击率（Crit Rate）。

* **左下角 (Mini-map - 小地图)：**
    * 实时显示周围地形和房间结构。
    * **绿色点**：玩家位置。
    * **蓝色区域**：起始房间。
    * **红色区域**：终点房间（第100层）。
    * *操作提示：点击小地图区域可进入全屏地图模式（支持滚轮缩放、鼠标拖拽）。*

* **右下角 (Stats - 统计数据)：**
    * **红色方框 - Floor：** 显示当前已探索的房间数进度（例如 18/100）。
    * **红色方框 - Deaths：** 显示玩家在本局游戏中的死亡/复活次数。

* **菜单系统：**
    * **主菜单：** 提供 "Load Saves"（读取存档）、"Settings"（设置）、"Support"（支持作者）等入口。
    * **设置菜单：** 支持调节 BGM/SFX 音量、切换全屏/窗口模式、显示 FPS 开关。
    * **键位绑定：** 支持自定义 Up/Down/Left/Right/Attack/Reload 的按键映射。

### 4.4 操作按键 (Controls)
*(以下为默认键位，大部分可在设置中修改)*

| 动作 | 按键 | 说明 |
| :--- | :--- | :--- |
| **移动** | **W / A / S / D** | 控制角色上下左右移动 |
| **攻击** | **J** 或 **鼠标左键** | 发射子弹 / 近战攻击 |
| **装填** | **R** | 重新装填弹药 |
| **菜单/暂停** | **ESC** | 呼出设置菜单或返回上一级 |
| **查看地图** | **点击左下角地图** | 进入大地图模式 |
| **地图交互** | **Ctrl + 滚轮** | 在大地图模式下缩放视图 |

---------------------

## 5. 贡献 (Contributing)
欢迎对本项目提交 Pull Request 或 Issue。
主要贡献者：
* **Withyoghurt** - 游戏设计、核心代码逻辑、UI设计、美术资源收集和整合等本工程全部的设计和实现工作。

---------------------

## 6. 许可证 (License)
* 本项目遵循 **MIT License** 开源协议。

---------------------

## 7. 联系方式 (Contact)
* 本工程设计者与制作者Withyoghurt的邮箱： weihongyu200533@163.com

---------------------

## 8. 致谢 (Acknowledgements)
* 感谢 Shen 老师精彩的 Python 课程教学。
* 全部像素美术素材和音频素材都参考自 OpenGameArt.org 和 AI生成工具。
* 特别感谢 `pygame` 社区的文档支持。