Qi-huanye/Loke

Fork 0

Files

T

FanstyNight 93ba207b74 补充文档和各类运行说明文件

2026-06-03 18:54:54 +08:00

8.9 KiB

Raw Permalink Blame History

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 为例：

sudo pacman -S cmake pkgconf gcc raylib pugixml

Debian / Ubuntu 系发行版的包名可能随版本不同而不同，通常需要安装：

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：

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

安装 Visual Studio Code。
安装 VS Code 扩展：C/C++ 和 CMake Tools。
安装 Visual Studio 2022 或 Build Tools for Visual Studio 2022，并勾选 Desktop development with C++ 工作负载。
用 VS Code 打开项目根目录，在 VS Code 终端中选择 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

从项目根目录启动游戏，并把 . 作为资源根目录传给程序：

.\build\Release\mana_pet_world.exe .

方式二：Visual Studio 2022

安装 Visual Studio 2022，并勾选 Desktop development with C++ 和 CMake 支持。
双击项目根目录下的 setup_vs2022.bat。脚本会安装 vcpkg 依赖、生成 build\vs2022\ManaPetWorld.sln、编译 mana_pet_world，然后打开 Visual Studio。
在 Visual Studio 中点击运行按钮即可启动游戏。CMake 已经把 mana_pet_world 设为启动项目，并把调试工作目录和启动参数设置为项目根目录。

如果你想手动执行，也可以打开 Developer PowerShell for VS 2022，进入项目根目录，运行：

$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，点击运行按钮；或者直接从命令行运行：

.\build\vs2022\Release\mana_pet_world.exe .

如果 CMake 报告找不到 raylib、pugixml 或 pkg-config，请先确认上面的 VCPKG_ROOT、PKG_CONFIG_PATH 和 PKG_CONFIG_EXECUTABLE 路径与本机 vcpkg 安装位置一致。

快速启动

在项目根目录运行：

./run.sh

这个脚本会执行三件事：

使用 CMake 配置 build/ 目录。
编译 mana_pet_world 可执行文件。
运行 build/mana_pet_world，并把项目根目录传给程序，让它能找到 assets/。

手动构建和运行

如果你不想使用脚本，可以手动执行：

cmake -S . -B build
cmake --build build --target mana_pet_world
./build/mana_pet_world .

程序会从第一个非 - 开头的参数推断项目根目录；没有传参时，会尝试从当前目录及上级目录中查找 assets/maps/tonori/tulimshar/tulimshar.tmx。

内容审计

检查地图、传送、小地图和任务目标覆盖情况：

./build/mana_pet_world --audit-world .

也可以通过启动脚本转发参数：

./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`

目录结构

.
├── 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 能找到依赖：

pkg-config --modversion raylib
pkg-config --modversion pugixml

如果命令失败，说明依赖没有安装，或者 pkg-config 搜索路径没有包含对应 .pc 文件。

启动后资源缺失或地图加载失败

请从项目根目录运行 ./run.sh，或手动运行时传入项目根目录：

./build/mana_pet_world /path/to/ManaPetWorld

程序需要通过根目录访问 assets/ 下的地图、贴图、字体、音乐和预设文件。

想清理构建产物

删除 build/ 后重新配置即可：

rm -rf build
cmake -S . -B build

8.9 KiB Raw Permalink Blame History Unescape Escape