From d58e076ede28a3de5837193e000a85900a8c9957 Mon Sep 17 00:00:00 2001 From: FanstyNight Date: Wed, 3 Jun 2026 17:21:32 +0800 Subject: [PATCH] =?UTF-8?q?=E9=87=8D=E5=86=99README.md?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 178 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 178 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..8fcc813 --- /dev/null +++ b/README.md @@ -0,0 +1,178 @@ +# ManaPetWorld + +ManaPetWorld 是一个用 C++20、raylib 和 pugixml 编写的 2D 冒险 / 宠物战斗游戏原型。项目直接读取 Tiled 地图、实体预设、任务预设、音效、音乐、字体和 UI 贴图等本地资源，启动后从 Tulimshar 地区开始探索。 + +![ManaPetWorld](assets/press/readme/header.png) + +## 项目内容 + +- 探索：加载 `assets/maps` 下的 TMX 地图与世界连接信息，支持城镇、洞穴、船只、沙漠等区域切换。 +- 交互：NPC 对话、宝箱、传送点、商店、任务目标和脚本化事件。 +- 宠物：初始宠物选择、野外宠物遭遇、捕捉、队伍 / 仓库、宠物图鉴和战斗。 +- 战斗：回合制战斗界面，支持技能、恢复道具、捕捉道具和逃跑。 +- 存档：进度保存到项目根目录的 `savegame.txt`。 +- 内容审计：内置 `--audit-world` 模式，用于检查地图、传送、小地图和任务目标覆盖情况。 + +![Combat](assets/press/readme/combat.png) + +## 环境要求 + +必需工具： + +- 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 找到对应库。 + +## 快速启动 + +在项目根目录运行： + +```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 +```