AGENTS.md

Working Agreements

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

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 不确定时，按这个顺序查：

docs/ui-baseline/ 和原 H5 运行截图。
muchang/home/web/game/ 中的 JS、EXML、资源 JSON。
muchang/ 里的 PHP/Yii 接口和 muchang_20211111_141209.sql。
Godot 4.6 官方文档和类参考。
官方没有覆盖时再查 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

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

检查单个脚本：

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 规则和配置验证：

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

工程导入检查：

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

Web 导出：

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

H5 smoke：

npm run smoke:godot:web

UI 图片对比：

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 和功能逻辑。

6.7 KiB Raw Permalink Blame History Unescape Escape