104 lines
4.1 KiB
Markdown
104 lines
4.1 KiB
Markdown
# AGENTS.md
|
||
|
||
本文件是本仓库给 AI 编码代理使用的项目 harness。开始修改前先读本文件和 `README.md`。
|
||
|
||
## 项目概况
|
||
|
||
- 项目名：`ManaPetWorld`
|
||
- 类型：C++20 2D 冒险 / 宠物战斗游戏原型
|
||
- 主要依赖：CMake、raylib、pugixml、pkg-config/pkgconf
|
||
- 主程序：`src/app/main.cpp`
|
||
- 可执行文件：`build/mana_pet_world`
|
||
- 资源根目录：`assets/`
|
||
- 存档文件：`savegame.txt`，位于仓库根目录，除非用户明确要求，不要修改或删除。
|
||
|
||
## 目录职责
|
||
|
||
- `src/app/`：主循环、运行时状态、输入、渲染入口。
|
||
- `src/core/`：宠物、元素、成长、核心数据模型。
|
||
- `src/battle/`：战斗界面、战斗资源、战斗布局。
|
||
- `src/world/`：TMX 地图加载、世界连接、传送、野外生成、地图审计。
|
||
- `src/dialogue/`：对话脚本、脚本化交互和对话效果。
|
||
- `src/quest/`：任务定义和任务进度。
|
||
- `src/save/`：存档读写。
|
||
- `src/assets/`：资源路径、图标、动画、音乐和音效索引。
|
||
- `src/ui/`：背包等 UI 模型和交互视觉辅助。
|
||
- `src/content/`：内置道具等内容表。
|
||
- `assets/maps/`：Tiled TMX 地图与 world 文件。
|
||
- `assets/presets/`：实体、任务、物品、调色板等预设。
|
||
- `assets/scripts/`：地图 / NPC 交互脚本。
|
||
- `assets/minimap/`：小地图资源。
|
||
|
||
## 构建和运行
|
||
|
||
优先使用仓库自带脚本：
|
||
|
||
```bash
|
||
./run.sh
|
||
```
|
||
|
||
手动构建：
|
||
|
||
```bash
|
||
cmake -S . -B build
|
||
cmake --build build --target mana_pet_world
|
||
./build/mana_pet_world .
|
||
```
|
||
|
||
修改 C++ 后至少运行：
|
||
|
||
```bash
|
||
cmake --build build --target mana_pet_world
|
||
```
|
||
|
||
修改地图、传送、小地图、任务目标或相关资源后运行：
|
||
|
||
```bash
|
||
./build/mana_pet_world --audit-world .
|
||
```
|
||
|
||
也可以通过脚本转发：
|
||
|
||
```bash
|
||
./run.sh --audit-world
|
||
```
|
||
|
||
## 开发规则
|
||
|
||
- 优先保持现有架构：通用游戏逻辑放进 `mana_core`，raylib 窗口和强渲染耦合逻辑放在可执行目标相关代码中。
|
||
- 新增 `.cpp` 文件时同步更新 `CMakeLists.txt`，否则不会参与构建。
|
||
- 头文件放在对应模块目录，沿用现有 include 风格。
|
||
- 保持 C++20，避免引入新第三方库，除非用户明确要求并说明构建影响。
|
||
- 代码应能通过现有编译选项：`-Wall -Wextra -Wpedantic`。
|
||
- 不要把生成的 `build/`、本地存档、临时文件或 IDE 产物加入版本控制。
|
||
- 不要大规模重排资源目录或重命名资产文件。很多路径由 TMX、预设、脚本或代码字符串引用。
|
||
- 修改二进制图片、字体、音乐、音效前必须确认这是用户要求的一部分。
|
||
- 修改 `.tmx`、`.tsx`、`.tres`、`.gd` 时，尽量保持原文件格式和命名约定，不做无关格式化。
|
||
|
||
## 内容修改注意事项
|
||
|
||
- 地图入口、传送对象、任务目标和小地图覆盖互相关联，改动后必须跑 `--audit-world`。
|
||
- 资源路径通常相对项目根目录解析，运行程序时传入 `.` 或项目绝对路径。
|
||
- 新增图标、精灵、音乐、音效后，检查对应的 catalog 或 asset 索引文件是否需要更新。
|
||
- 新增实体或任务时，检查 `assets/presets/`、`assets/scripts/`、地图对象引用和 C++ 内容加载逻辑是否一致。
|
||
|
||
## 验证要求
|
||
|
||
根据改动范围选择验证命令：
|
||
|
||
- 只改文档：无需构建，检查 Markdown 内容即可。
|
||
- 改 C++：运行 `cmake --build build --target mana_pet_world`。
|
||
- 首次构建或 `build/` 不存在：先运行 `cmake -S . -B build`。
|
||
- 改世界内容：运行 `./build/mana_pet_world --audit-world .`。
|
||
- 改启动流程：运行 `./run.sh --audit-world` 或说明为什么不能运行图形程序。
|
||
|
||
如果验证命令因缺少系统依赖失败，报告缺少的依赖和失败命令，不要伪造通过结果。
|
||
|
||
## 代理行为约束
|
||
|
||
- 修改前先用 `rg`、`rg --files` 或相关源码阅读确认现有模式。
|
||
- 保持改动小而集中，不做无关重构。
|
||
- 不回滚用户已有改动。
|
||
- 不执行破坏性命令，除非用户明确要求。
|
||
- 最终回复必须说明改了哪些文件、是否运行验证、验证结果或未运行原因。
|