4.1 KiB
4.1 KiB
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/：小地图资源。
构建和运行
优先使用仓库自带脚本：
./run.sh
手动构建：
cmake -S . -B build
cmake --build build --target mana_pet_world
./build/mana_pet_world .
修改 C++ 后至少运行：
cmake --build build --target mana_pet_world
修改地图、传送、小地图、任务目标或相关资源后运行：
./build/mana_pet_world --audit-world .
也可以通过脚本转发：
./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或相关源码阅读确认现有模式。 - 保持改动小而集中，不做无关重构。
- 不回滚用户已有改动。
- 不执行破坏性命令，除非用户明确要求。
- 最终回复必须说明改了哪些文件、是否运行验证、验证结果或未运行原因。