145 lines
6.7 KiB
Markdown
145 lines
6.7 KiB
Markdown
# 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 和功能逻辑。
|