# AGENTS.md

## Working Agreements

1. 做任何事情之前不要猜测，先查本地代码、资源、文档、原 H5 行为或官方 API，找最直接的解决方案。
2. 所有解决的问题都必须验证。不能只改代码不跑检查。
3. 修改时碰到已有改动无需询问，继续在现有改动基础上工作；不要回滚用户或其他代理的改动。
4. UI 以原版 H5 运行截图和 Egret 资源为验收标准，不能用“差不多”替代一致。
5. 性能优先。新增功能要避免全量重绘、重复加载纹理、常驻无意义 `_process` 和过度创建节点。
6. 遇到缺失工具可以直接安装，但要优先使用项目现有工具链，并在最终说明里写清验证命令。

## Project Scope

这是 Egret H5 农场游戏到 Godot 4.6.2 的 H5 重构项目。

- Godot 工程：`godot/FarmGodot`
- 启动场景：`godot/FarmGodot/scenes/bootstrap.tscn`
- 主 UI 场景：`godot/FarmGodot/scenes/ui/game_scene.tscn`
- 主场景脚本：`godot/FarmGodot/scripts/ui/game_scene.gd`
- 原 H5/后端参考：`muchang/`
- UI 基准和 smoke 截图：`docs/ui-baseline/`

默认自动登录在 `godot/FarmGodot/scripts/bootstrap.gd`：

- 账号：`13800000001`
- 密码：`123456`

后端地址配置在 `godot/FarmGodot/project.godot`：

- `farm_game/api/base_url = http://127.0.0.1:18082/index.php?r=`
- `farm_game/api/login_path = user/login`

## Current Architecture

`game_scene.gd` 当前是主场景协调层，目标是保持很薄。不要把新功能大块写回这个文件。

核心装配和运行时模块：

- `scripts/ui/game_scene.gd`：场景生命周期、节点引用、少量状态同步和跨模块回调桥接。
- `scripts/ui/game_scene_bootstrap.gd`：创建服务、状态、规则、资源缓存、Facade、Controller 和 Panel。
- `scripts/ui/game_scene_runtime_assembler.gd`：装配 HUD、菜单、ModalLayer、宠物展示、缩放根节点、土地网格、土地菜单、种子包、种植提示和 hit 路由。
- `scripts/ui/game_scene_panel_router.gd`：统一面板入口、弹窗打开/关闭、房屋/土地扩建入口、宠物/活动/支付等面板打开流程。
- `scripts/ui/scene_hit_router.gd`：顶部、左侧、建筑、宠物等点击热区和直接命中兜底。
- `scripts/ui/farm/farm_interaction_coordinator.gd`：土地点击、长按、选中光圈、动作菜单、背包和作物提示交互。

业务分层：

- `scripts/services/`：后端 API。网络请求必须走 `ApiClient` 和对应 `*_api.gd`。
- `scripts/state/`：玩家、农场、库存等本地状态和 Facade。
- `scripts/domain/rules/`：纯规则判断，例如作物阶段、土地动作、消耗判断。
- `scripts/domain/mappers/`：后端数据到 Godot 本地结构的归一化。
- `scripts/resources/`：Egret 图集区域和 `AtlasTexture` 缓存。
- `scripts/ui/common/`：通用 UI 构建、纹理提供、弹窗层、动效工具。
- `scripts/ui/panels/`：各功能面板。新增面板优先继承或复用 `PanelModule`、`UiBuilder`、`TextureProvider`。

当前 `game_scene.gd` 已降到 1200 行以内。后续架构目标是把跨模块回调字典继续收敛为显式 `GameSceneContext`，并保持新增功能独立成模块。

## Source Lookup Order

遇到行为、接口、资源或 UI 不确定时，按这个顺序查：

1. `docs/ui-baseline/` 和原 H5 运行截图。
2. `muchang/home/web/game/` 中的 JS、EXML、资源 JSON。
3. `muchang/` 里的 PHP/Yii 接口和 `muchang_20211111_141209.sql`。
4. Godot 4.6 官方文档和类参考。
5. 官方没有覆盖时再查 GitHub 或社区资料，并记录来源。

不要凭记忆猜接口名、资源名、节点坐标、Godot API 或原版 UI 行为。

## Implementation Rules

- 新功能先判断归属层级：接口进 `services/`，状态进 `state/`，规则进 `domain/`，资源进 `resources/`，显示进 `ui/`。
- 新面板放到 `scripts/ui/panels/<feature>_panel.gd`，不要堆进 `game_scene.gd`。
- 新主场景入口接入 `GameScenePanelRouter` 或 `SceneHitRouter`，不要在场景脚本里新增一串 `_open_*` 包装。
- 土地相关交互优先放入 `FarmInteractionCoordinator`、`LandGridView`、`LandActionMenu`、`SeedBagView`、`PlantTipView`。
- 背包、奖励、消耗、货币变更优先走 `PlayerInventoryFacade`。
- 玩家快照字段访问优先走 `PlayerState`，避免新增 `_player_data.get()` 或 `_player_data[...]`。
- 跨 UI 模块共享能力优先走 `GameSceneContext`，不要在 Bootstrap 或面板里新增大 callback 字典。
- 图集和图标纹理优先走 `TextureProvider`、`IconTextureProvider` 和 `AtlasTextureCache`，不要重复 `load()` 大图或手动裁剪。
- Egret `scale9Grid` 对应 Godot `NinePatchRect`，不要用普通 `TextureRect` 直接拉伸九宫格素材。
- UI 坐标优先参考 EXML、原图集 JSON 和现有面板实现，不要目测随意摆。

## Coding Standards

- 使用 Godot 4.6.2 stable，非 .NET 版本。
- 只写 GDScript。
- Web 渲染路径保持 Compatibility。
- 文件、函数、变量使用 `snake_case`。
- 常量使用 `ALL_CAPS`。
- 尽量使用明确类型标注，但公共 helper 入口需要兼容普通 `Array` 时不要过度收窄为 `Array[String]`。
- 使用 `and`、`or`、`not`，不要写 `&&`、`||`、`!`。
- 控件文本要保证移动端不溢出、不重叠。
- 新增复杂逻辑只写必要注释，不写空泛注释。

## Verification Commands

按修改范围选择验证，不要省略。

检查单个脚本：

```sh
godot --headless --path godot/FarmGodot --check-only --script res://scripts/ui/game_scene.gd
godot --headless --path godot/FarmGodot --check-only --script res://scripts/ui/game_scene_bootstrap.gd
godot --headless --path godot/FarmGodot --check-only --script res://scripts/ui/game_scene_runtime_assembler.gd
godot --headless --path godot/FarmGodot --check-only --script res://scripts/ui/game_scene_panel_router.gd
```

P0 规则和配置验证：

```sh
godot --headless --path godot/FarmGodot --script res://tools/verify_p0.gd
```

工程导入检查：

```sh
godot --headless --path godot/FarmGodot --import --quit
```

Web 导出：

```sh
godot --headless --path godot/FarmGodot --export-release Web build/web/index.html
```

H5 smoke：

```sh
npm run smoke:godot:web
```

UI 图片对比：

```sh
npm run compare:ui -- <egret.png> <godot.png> <diff.png>
```

## Safety Rules

- 不要执行 `git reset --hard`、`git checkout --` 等破坏性命令，除非用户明确要求。
- 不要删除原始资源、SQL、原 H5、解密 HTML、基准截图或 Web 导出配置。
- 不要把临时 `print`、`DEBUG`、一次性截图脚本长期留在代码里。
- 不要引入第三方库，除非官方方案不能解决，并且记录版本、来源和许可证。
- 不要把 UI 改成新风格。目标是复刻原版 UI 和功能逻辑。