# 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` 或相关源码阅读确认现有模式。
- 保持改动小而集中，不做无关重构。
- 不回滚用户已有改动。
- 不执行破坏性命令，除非用户明确要求。
- 最终回复必须说明改了哪些文件、是否运行验证、验证结果或未运行原因。