# 遗迹突围UE5

**Repository Path**: wmx2671/game-based-learning

## Basic Information

- **Project Name**: 遗迹突围UE5
- **Description**: 这是 AI 辅助开发的学习工程，展示和讨论以实际理解、修改及验证过的代码为依据。依赖和素材来源见
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-10-23
- **Last Updated**: 2026-10-23

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 遗迹突围 Ruins Breakout

基于 **Unreal Engine 5.6 / C++** 的单机俯视角动作战斗 Demo。玩家在遗迹竞技场中完成三波战斗，选择强化，击败守卫后前往星门撤离。

项目覆盖角色控制、战斗判定、状态机、生命组件、UMG、DataTable 与自动化测试，作为游戏客户端开发学习工程持续完善。

**版本：0.1.0 · 文档更新：2026-10-23**

本仓库包含源码、配置、地图、材质、音效和数据表。Windows EXE、引擎、安装器及编译缓存不在 Git 中，首次运行需要准备 UE 和 C++ 构建环境。

## 当前功能

| 模块 | 实现内容 |
| --- | --- |
| 玩家 | WASD 移动、鼠标朝向、近战挥击、闪避、范围技能、药剂 |
| 战斗 | 冷却、能量恢复、无敌时间、伤害、死亡、扇形与遮挡判定 |
| 敌人 | 近战巡戈者、远程祭司、守卫；追击、预警、攻击、恢复 |
| 游戏流程 | 三波共 13 个敌人、波间强化、撤离、暂停、胜负结算、重开 |
| 界面 | 生命、能量、药剂、技能冷却、Boss 血条、菜单及结算 |
| 配置 | CSV 校验，敌人和波次 DataTable 导入与读取 |
| 存档 | 使用本地 SaveGame 保存最高分 |
| 测试 | 52 项纯 C++ 规则检查、11 项 Python unittest、UE 游戏流程集成测试 |

角色和场景使用引擎基础几何体，场景在运行时生成。当前战斗逻辑主要在角色类中，生命已拆为 ActorComponent；HUD 主要每帧读取状态刷新。

## 环境要求

- Windows x64。
- Unreal Engine **5.6.x**，已有工程验证版本为 **5.6.1**。
- Visual Studio 2022 C++ 构建工具及兼容的 Windows SDK；原开发环境使用 MSVC 14.38.33130、Windows SDK 10.0.22621.0。
- 独立 Python 配置测试仅依赖标准库；UE 资产生成使用引擎内置 Python。
- 项目已声明 Enhanced Input、Python Script Plugin 和 Editor Scripting Utilities 插件。

引擎通过 Epic Games Launcher 安装，编译工具可通过 Visual Studio Installer 安装。根目录的 `CheckEnvironment.cmd` 可检查本机依赖；`InstallDependencies.cmd` 是可选安装入口，使用前请阅读脚本中的默认安装路径。

## 克隆与首次启动

建议克隆到英文路径，避免部分构建工具对中文路径的兼容问题。以下示例中的引擎路径请替换为本机实际位置，该目录下应有 `Engine` 子目录。

```powershell
git clone https://gitee.com/wmx2671/game-based-learning.git
Set-Location game-based-learning

# 编译 Editor、生成或更新资源，然后启动游戏
.\Scripts\Launch.ps1 -FromSource -EngineRoot 'E:\EpicGames\UE_5.6\UE_5.6'

# 编译、更新资源并打开编辑器
.\Scripts\Launch.ps1 -Mode Editor -EngineRoot 'E:\EpicGames\UE_5.6\UE_5.6'
```

编辑器地图为 `/Game/Maps/RuinsArena`。进入 Play 后，`ARuinsArena` 会生成遗迹场景。

脚本可从 `-EngineRoot`、环境变量 `RUINS_UE_ROOT`、本地 `.ue-root`、Epic 安装记录及常用目录查找 UE。首次初始化成功后会保存本机引擎路径，`.ue-root` 已被 Git 忽略。

若 PowerShell 执行策略阻止脚本，可以使用根目录的 `StartGame.cmd` / `OpenEditor.cmd`，或进行单次进程调用：

```powershell
powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\Scripts\Launch.ps1 -FromSource -EngineRoot 'E:\EpicGames\UE_5.6\UE_5.6'
```

**`StartGame.cmd` 会优先运行本机已有的 `Builds\Windows\RuinsBreakout.exe`。** 修改源码或资源后，请使用 `-FromSource` 验证当前工程，或重新打包。旧 EXE 不会自动包含新的修改。

## 操作与玩法

| 输入 | 行为 |
| --- | --- |
| WASD | 移动 |
| 鼠标指向 | 角色朝向 |
| 鼠标左键 / J | 近战挥击 |
| 空格 / 左 Shift | 闪避，消耗 25 能量并获得短暂无敌 |
| Q | 范围震荡，消耗 45 能量，冷却 5 秒 |
| E | 使用治疗药剂；初始 2 瓶，每瓶最多恢复 40 生命 |
| F | 最后一波结束后，在北侧星门附近撤离 |
| ESC / 暂停按钮 | 暂停或继续 |

| 波次 | 巡戈者 | 祭司 | 守卫 |
| --- | ---: | ---: | ---: |
| 第 1 波 | 4 | 0 | 0 |
| 第 2 波 | 3 | 2 | 0 |
| 第 3 波 | 2 | 1 | 1 |

前两波结束后可从攻击、生命、机动中选择一项强化。击杀恢复少量生命和能量；第三波结束后需要抵达星门并按 F 才算胜利。本地最高分存档槽名为 `RuinsLocalBest`。

## 数据与资源

- `Data/Enemies.csv`：生命、速度、伤害、范围、预警、恢复、得分及敌人类型。
- `Data/Waves.csv`：每波三种敌人的数量。
- `Tools/validate_config.py`：字段、重复 ID、数值和波次约束检查。
- `Tools/bootstrap_unreal.py`：UE 内创建或更新地图、材质、DataTable 和音效。
- `Tools/generate_audio.py`：使用标准库合成 8 个音效。

```powershell
python .\Tools\validate_config.py
.\Scripts\Initialize.ps1 -EngineRoot 'E:\EpicGames\UE_5.6\UE_5.6'
.\Scripts\Launch.ps1 -FromSource -SkipInitialize
```

修改 CSV 后需要重新导入 DataTable；修改 C++ 后需要重新编译。仅在初始化成功且代码、资源未再变化时使用 `-SkipInitialize`。

`Tools/import_art.py` 和 `Scripts/ImportArt.ps1` 是可选美术导入工具，需要另行准备对应授权素材。相关原始素材和未接入玩法的 `Content/Art` 未随仓库提交，默认游戏运行不依赖它们。

## 测试

### 独立规则和配置测试

不需要启动 Unreal Engine。以下工具路径请按本机环境修改：

```powershell
# MSVC
.\Scripts\Test.ps1 -Python 'python' -VisualStudio 'E:\DevTools\VS2022'

# 或 MinGW
.\Scripts\Test.ps1 -Python 'python' -Gpp 'E:\mingw64\bin\g++.exe'
```

纯 C++ 测试覆盖伤害、无敌、药剂、能量、冷却、强化、扇形、暂停与结算；11 项配置测试使用 Python `unittest`。

### Unreal 集成测试

```powershell
.\Scripts\Initialize.ps1 -EngineRoot 'E:\EpicGames\UE_5.6\UE_5.6'
.\Scripts\TestIntegration.ps1 -UseEditor -EngineRoot 'E:\EpicGames\UE_5.6\UE_5.6'
```

测试名为 `Ruins.Integration.GameFlow`，在真实 UE 游戏世界中检查碰撞、伤害、波次、暂停、撤离、存档与重开，报告位于 `Saved/Verification/Integration/index.json`。

无渲染集成测试不能代替画面、声音和操作手感的人工验证。验证日期和范围见 [验证记录](Docs/VERIFICATION.md)，手工步骤见 [验收清单](Docs/MANUAL_TESTS.md)。

## Windows 打包

```powershell
.\Scripts\Package.ps1 -EngineRoot 'E:\EpicGames\UE_5.6\UE_5.6'
```

也可双击 `PackageWindows.cmd`。默认构建配置为 Development，输出到 `Builds/Windows`。运行入口是 `Builds/Windows/RuinsBreakout.exe`；分发时保留整个 Windows 目录。

## 代码阅读顺序

| 文件 | 阅读重点 |
| --- | --- |
| [RuinsRules.h](Source/RuinsBreakout/Public/RuinsRules.h) | 不依赖引擎的规则和状态机 |
| [rules_tests.cpp](Tests/rules_tests.cpp) | 边界条件、重复消费与重复结算保护 |
| [RuinsPlayer.cpp](Source/RuinsBreakout/Private/RuinsPlayer.cpp) | 输入、朝向、攻击时机、闪避和遮挡 |
| [RuinsEnemy.cpp](Source/RuinsBreakout/Private/RuinsEnemy.cpp) | 敌人状态、局部避障、分离与弹丸 |
| [RuinsHealthComponent.cpp](Source/RuinsBreakout/Private/RuinsHealthComponent.cpp) | 生命封装与死亡委托 |
| [RuinsGameMode.cpp](Source/RuinsBreakout/Private/RuinsGameMode.cpp) | 波次、配置、强化、存档与场景生成 |
| [RuinsWidget.cpp](Source/RuinsBreakout/Private/RuinsWidget.cpp) | UMG 控件树和界面交互 |

一次近战攻击的流程：输入 → 检查游戏状态与冷却 → 开始挥击 → 到达伤害时机 → 检查扇形和遮挡 → 敌人扣血 → 死亡事件 → 更新分数与波次。

## 后续方向

- 通用背包、掉落、拾取和道具配置；目前只有药剂数量与使用规则。
- 战斗组件拆分、以事件通知为主的 HUD 更新。
- HTTP 联网排行榜及回调生命周期管理；目前最高分为本地存档。
- Editor Utility Widget 配置预检、导入、日志面板和更通用的跨表校验。
- 美术模型、骨骼动画和复杂场景寻路。
- 敌人分离查询与动态材质实例缓存优化；当前未提供性能基准数据。

以上均为待完善方向。当前工程没有多人同步；局部避障也不等同于完整的 A* 寻路。

这是 AI 辅助开发的学习工程，展示和讨论以实际理解、修改及验证过的代码为依据。依赖和素材来源见 [THIRD_PARTY.md](THIRD_PARTY.md)。