243 lines
8.9 KiB
Markdown
243 lines
8.9 KiB
Markdown
# ManaPetWorld
|
||
|
||
https://git.qihuanye.cn/qihuanye/Loke.git *代码仓库*
|
||
|
||
ManaPetWorld 是一个用 C++20、raylib 和 pugixml 编写的 2D 冒险 / 宠物战斗游戏原型。项目直接读取 Tiled 地图、实体预设、任务预设、音效、音乐、字体和 UI 贴图等本地资源，启动后从 Tulimshar 地区开始探索。
|
||
|
||
|
||
|
||
## 项目内容
|
||
|
||
- 探索：加载 `assets/maps` 下的 TMX 地图与世界连接信息，支持城镇、洞穴、船只、沙漠等区域切换。
|
||
- 交互：NPC 对话、宝箱、传送点、商店、任务目标和脚本化事件。
|
||
- 宠物：初始宠物选择、野外宠物遭遇、捕捉、队伍 / 仓库、宠物图鉴和战斗。
|
||
- 战斗：回合制战斗界面，支持技能、恢复道具、捕捉道具和逃跑。
|
||
- 存档：进度保存到项目根目录的 `savegame.txt`。
|
||
- 内容审计：内置 `--audit-world` 模式，用于检查地图、传送、小地图和任务目标覆盖情况。
|
||
|
||
|
||
## 环境要求
|
||
|
||
必需工具：
|
||
|
||
- CMake 3.20+
|
||
- 支持 C++20 的编译器
|
||
- pkg-config / pkgconf
|
||
- raylib
|
||
- pugixml
|
||
|
||
Linux 上推荐直接安装系统依赖。以 Arch Linux 为例：
|
||
|
||
```bash
|
||
sudo pacman -S cmake pkgconf gcc raylib pugixml
|
||
```
|
||
|
||
Debian / Ubuntu 系发行版的包名可能随版本不同而不同，通常需要安装：
|
||
|
||
```bash
|
||
sudo apt install cmake pkg-config g++ libraylib-dev libpugixml-dev
|
||
```
|
||
|
||
仓库中也包含 `vcpkg.json`，声明了 `raylib` 和 `pugixml` 依赖；如果你使用 vcpkg，请确保 CMake 能通过 pkg-config 找到对应库。
|
||
|
||
### Windows 构建和运行
|
||
|
||
下面给出两种 Windows 运行方式：**PowerShell + VS Code** 和 **Visual Studio 2022**。两种方式都使用 vcpkg 安装依赖。当前 CMake 配置通过 `pkg-config` 查找 `raylib` 和 `pugixml`，所以除了游戏依赖本身，还需要安装 `pkgconf`。
|
||
|
||
先准备通用依赖。下面假设 vcpkg 安装在 `C:\src\vcpkg`：
|
||
|
||
```powershell
|
||
git clone https://github.com/microsoft/vcpkg C:\src\vcpkg
|
||
C:\src\vcpkg\bootstrap-vcpkg.bat
|
||
C:\src\vcpkg\vcpkg.exe install raylib pugixml pkgconf --triplet x64-windows
|
||
```
|
||
|
||
#### 方式一：PowerShell + VS Code
|
||
|
||
1. 安装 Visual Studio Code。
|
||
2. 安装 VS Code 扩展：**C/C++** 和 **CMake Tools**。
|
||
3. 安装 Visual Studio 2022 或 Build Tools for Visual Studio 2022，并勾选 **Desktop development with C++** 工作负载。
|
||
4. 用 VS Code 打开项目根目录，在 VS Code 终端中选择 PowerShell，然后运行：
|
||
|
||
```powershell
|
||
$env:VCPKG_ROOT = "C:\src\vcpkg"
|
||
$env:PKG_CONFIG_PATH = "$env:VCPKG_ROOT\installed\x64-windows\lib\pkgconfig;$env:VCPKG_ROOT\installed\x64-windows\share\pkgconfig"
|
||
|
||
cmake -S . -B build -G "Visual Studio 17 2022" -A x64 `
|
||
-DCMAKE_TOOLCHAIN_FILE="$env:VCPKG_ROOT\scripts\buildsystems\vcpkg.cmake" `
|
||
-DPKG_CONFIG_EXECUTABLE="$env:VCPKG_ROOT\installed\x64-windows\tools\pkgconf\pkgconf.exe"
|
||
|
||
cmake --build build --config Release --target mana_pet_world
|
||
```
|
||
|
||
5. 从项目根目录启动游戏，并把 `.` 作为资源根目录传给程序：
|
||
|
||
```powershell
|
||
.\build\Release\mana_pet_world.exe .
|
||
```
|
||
|
||
#### 方式二：Visual Studio 2022
|
||
|
||
1. 安装 Visual Studio 2022，并勾选 **Desktop development with C++** 和 CMake 支持。
|
||
2. 双击项目根目录下的 `setup_vs2022.bat`。脚本会安装 vcpkg 依赖、生成 `build\vs2022\ManaPetWorld.sln`、编译 `mana_pet_world`，然后打开 Visual Studio。
|
||
3. 在 Visual Studio 中点击运行按钮即可启动游戏。CMake 已经把 `mana_pet_world` 设为启动项目，并把调试工作目录和启动参数设置为项目根目录。
|
||
|
||
如果你想手动执行，也可以打开 **Developer PowerShell for VS 2022**，进入项目根目录，运行：
|
||
|
||
```powershell
|
||
$env:VCPKG_ROOT = "C:\src\vcpkg"
|
||
$env:PKG_CONFIG_PATH = "$env:VCPKG_ROOT\installed\x64-windows\lib\pkgconfig;$env:VCPKG_ROOT\installed\x64-windows\share\pkgconfig"
|
||
|
||
cmake -S . -B build\vs2022 -G "Visual Studio 17 2022" -A x64 `
|
||
-DCMAKE_TOOLCHAIN_FILE="$env:VCPKG_ROOT\scripts\buildsystems\vcpkg.cmake" `
|
||
-DPKG_CONFIG_EXECUTABLE="$env:VCPKG_ROOT\installed\x64-windows\tools\pkgconf\pkgconf.exe"
|
||
|
||
cmake --build build\vs2022 --config Release --target mana_pet_world
|
||
```
|
||
|
||
然后打开 `build\vs2022\ManaPetWorld.sln`，点击运行按钮；或者直接从命令行运行：
|
||
|
||
```powershell
|
||
.\build\vs2022\Release\mana_pet_world.exe .
|
||
```
|
||
|
||
如果 CMake 报告找不到 `raylib`、`pugixml` 或 `pkg-config`，请先确认上面的 `VCPKG_ROOT`、`PKG_CONFIG_PATH` 和 `PKG_CONFIG_EXECUTABLE` 路径与本机 vcpkg 安装位置一致。
|
||
|
||
## 快速启动
|
||
|
||
在项目根目录运行：
|
||
|
||
```bash
|
||
./run.sh
|
||
```
|
||
|
||
这个脚本会执行三件事：
|
||
|
||
1. 使用 CMake 配置 `build/` 目录。
|
||
2. 编译 `mana_pet_world` 可执行文件。
|
||
3. 运行 `build/mana_pet_world`，并把项目根目录传给程序，让它能找到 `assets/`。
|
||
|
||
## 手动构建和运行
|
||
|
||
如果你不想使用脚本，可以手动执行：
|
||
|
||
```bash
|
||
cmake -S . -B build
|
||
cmake --build build --target mana_pet_world
|
||
./build/mana_pet_world .
|
||
```
|
||
|
||
程序会从第一个非 `-` 开头的参数推断项目根目录；没有传参时，会尝试从当前目录及上级目录中查找 `assets/maps/tonori/tulimshar/tulimshar.tmx`。
|
||
|
||
## 内容审计
|
||
|
||
检查地图、传送、小地图和任务目标覆盖情况：
|
||
|
||
```bash
|
||
./build/mana_pet_world --audit-world .
|
||
```
|
||
|
||
也可以通过启动脚本转发参数：
|
||
|
||
```bash
|
||
./run.sh --audit-world
|
||
```
|
||
|
||
审计输出会列出地图数量、出生点、传送数量、缺失传送、小地图覆盖和任务目标地图覆盖等信息。这个命令适合在修改 TMX 地图、传送对象、任务目标或小地图资源后运行。
|
||
|
||
## 操作键位
|
||
|
||
| 场景 | 操作 |
|
||
| --- | --- |
|
||
| 移动 | `W` `A` `S` `D` |
|
||
| 奔跑 | `Shift` |
|
||
| 对话 / 交互 / 确认入口 | `E` |
|
||
| 暂停 / 返回 | `Esc` 或 `B` |
|
||
| 世界地图 | `M` |
|
||
| 任务日志 | `L` |
|
||
| 背包 / 队伍 | `I` |
|
||
| 背包页面切换 | `Tab` |
|
||
| 道具分类切换 | `Q` / `E` |
|
||
| 宠物图鉴 | `P` |
|
||
| 观察模式 | `O` |
|
||
| 坐标调试 | `F3` |
|
||
| 保存 | `F5` |
|
||
| 读取存档 | `F9` |
|
||
| 召唤 / 收回首发宠物 | `R` |
|
||
| 投掷捕捉符 | `F` |
|
||
| 战斗选择 | `1`-`4`、方向键或鼠标 |
|
||
| 战斗捕捉道具 | `C` |
|
||
| 战斗逃跑 | `Esc` |
|
||
|
||
## 目录结构
|
||
|
||
```text
|
||
.
|
||
├── CMakeLists.txt # CMake 构建配置
|
||
├── run.sh # 一键配置、编译并启动
|
||
├── vcpkg.json # vcpkg 依赖声明
|
||
├── src/
|
||
│ ├── app/ # 主程序、运行时状态、渲染和输入循环
|
||
│ ├── assets/ # 资源目录解析、图标、动画、音乐和音效索引
|
||
│ ├── battle/ # 战斗状态、布局和战斗界面
|
||
│ ├── content/ # 内置道具等游戏内容
|
||
│ ├── core/ # 宠物、元素、成长和核心数据模型
|
||
│ ├── dialogue/ # 对话脚本与对话效果
|
||
│ ├── quest/ # 任务定义和任务进度
|
||
│ ├── save/ # 存档读写
|
||
│ ├── ui/ # 背包等 UI 模型和视觉辅助
|
||
│ └── world/ # TMX 地图、世界索引、传送和野外生成
|
||
└── assets/
|
||
├── maps/ # Tiled TMX 地图与 world 文件
|
||
├── tilesets/ # Tiled tileset 定义
|
||
├── presets/ # 实体、任务、物品、调色板等预设
|
||
├── scripts/ # 地图 / NPC 交互脚本
|
||
├── sprites/ # 玩家、NPC、怪物、装备等精灵图
|
||
├── ui/ # UI 贴图
|
||
├── minimap/ # 小地图资源
|
||
├── battle/ # 战斗相关资源
|
||
├── music/ # 背景音乐
|
||
├── sounds/ # 音效
|
||
├── fonts/ # 字体
|
||
└── press/ # README 和启动界面用图
|
||
```
|
||
|
||
## 开发提示
|
||
|
||
- 修改 C++ 后运行 `cmake --build build --target mana_pet_world` 重新编译。
|
||
- 修改地图、传送、小地图或任务后运行 `./build/mana_pet_world --audit-world .` 做内容检查。
|
||
- 资源路径大多相对项目根目录解析；从其他目录启动时，建议显式传入项目根目录。
|
||
- 存档文件是 `savegame.txt`，位于项目根目录。需要重新开始时，可以在游戏标题界面选择新游戏覆盖存档。
|
||
|
||
## 常见问题
|
||
|
||
### CMake 找不到 raylib 或 pugixml
|
||
|
||
确认 `pkg-config` 能找到依赖：
|
||
|
||
```bash
|
||
pkg-config --modversion raylib
|
||
pkg-config --modversion pugixml
|
||
```
|
||
|
||
如果命令失败，说明依赖没有安装，或者 pkg-config 搜索路径没有包含对应 `.pc` 文件。
|
||
|
||
### 启动后资源缺失或地图加载失败
|
||
|
||
请从项目根目录运行 `./run.sh`，或手动运行时传入项目根目录：
|
||
|
||
```bash
|
||
./build/mana_pet_world /path/to/ManaPetWorld
|
||
```
|
||
|
||
程序需要通过根目录访问 `assets/` 下的地图、贴图、字体、音乐和预设文件。
|
||
|
||
### 想清理构建产物
|
||
|
||
删除 `build/` 后重新配置即可：
|
||
|
||
```bash
|
||
rm -rf build
|
||
cmake -S . -B build
|
||
```
|