Farm3 Godot H5 重构

这是一个把原 Egret H5 农场游戏重构到 Godot 4.6.2 的项目。目标是保留原版 UI、动效、后端协议和核心玩法，同时把旧的大脚本拆成可维护、高性能的模块化结构。

当前状态

• Godot 工程可以自动登录并进入农场主场景。
• 默认账号：13800000001 / 123456。
• 主农场基础闭环已接入：播种、收获、铲除、施肥、浇水、除草、除虫、倒计时、成熟点击。
• 主场景入口已接入：商店、仓库、好友、日志、土地升级、充值、等级礼包、幸运转盘、宝箱、福利大厅、系统公告、每日签到、在线礼包、兑换金币、世界菜单、宠物显示。
• 土地场景支持双指和滚轮缩放，UI 层不跟随缩放。
• P0 架构拆分已完成，game_scene.gd 已降到 1200 行以内。
• UI 基准截图和 smoke 截图保存在 docs/ui-baseline/。

目录结构

.
├── AGENTS.md                     # 本项目代理开发规范
├── README.md                     # 项目说明
├── docs/                         # 架构、迁移、优先级和 UI 基准文档
├── godot/FarmGodot/              # Godot 4.6.2 工程
│   ├── assets/egret/             # 从原 Egret H5 迁移的资源
│   ├── build/web/                # Web 导出产物
│   ├── scenes/                   # Godot 场景
│   ├── scripts/                  # GDScript 代码
│   └── tools/                    # Godot 侧验证脚本
├── muchang/                      # 原 H5、PHP/Yii 后端和运行参考
├── muchang_20211111_141209.sql   # 原数据库备份
├── package.json                  # Web smoke 和 UI diff 工具命令
└── tools/                        # Node/Playwright 验证工具

技术栈

• Godot 4.6.2.stable.official.71f334935
• GDScript
• Godot Web/H5 导出
• Compatibility 渲染
• Egret 原始图集、EXML、配置和后端协议
• Node.js + Playwright smoke

确认 Godot 版本：

godot --version

后端配置

后端地址在：

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"

自动登录账号在：

godot/FarmGodot/scripts/bootstrap.gd

const AUTO_USERNAME := "13800000001"
const AUTO_PASSWORD := "123456"

运行工程

从仓库根目录运行 Godot：

godot --path godot/FarmGodot

无界面导入检查：

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

导出 H5

从仓库根目录运行：

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

导出产物：

godot/FarmGodot/build/web/

启动本地预览：

python3 -m http.server 8792 --directory godot/FarmGodot/build/web

浏览器打开：

http://127.0.0.1:8792/index.html

验证命令

安装 Node 依赖：

npm install
npx playwright install chromium

检查关键脚本：

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
godot --headless --path godot/FarmGodot --check-only --script res://scripts/ui/common/ui_builder.gd

检查 P0 规则和配置：

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

导出后跑 H5 smoke：

npm run smoke:godot:web

UI 图片对比：

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

当前架构

godot/FarmGodot/scripts/
├── bootstrap.gd                  # 自动登录、加载主场景
├── core/                         # 配置目录、数字格式、位图文字
├── domain/
│   ├── mappers/                  # 后端数据归一化
│   └── rules/                    # 作物阶段、土地动作、消耗判断
├── farm/                         # 农场操作控制器
├── resources/                    # 图集区域和 AtlasTexture 缓存
├── services/                     # 后端 API 服务
├── state/                        # 玩家、农场、库存状态和 Facade
└── ui/
    ├── common/                   # UiBuilder、TextureProvider、Modal、动效
    ├── farm/                     # 土地网格、动作菜单、背包、种植提示、缩放
    ├── hud/                      # 顶部 HUD
    ├── menus/                    # 主菜单、世界菜单
    ├── panels/                   # 各功能面板
    ├── game_scene.gd             # 主场景协调层
    ├── game_scene_context.gd     # 跨模块上下文和 legacy callback 兼容层
    ├── game_scene_bootstrap.gd   # 服务/状态/面板装配
    ├── game_scene_runtime_assembler.gd
    ├── game_scene_panel_router.gd
    └── scene_hit_router.gd

核心职责：

• GameScene：只保留生命周期、节点引用、土地快照渲染和少量上下文桥接。
• GameSceneContext：统一提供玩家状态、资源纹理、面板路由和旧面板 callback 兼容入口。
• GameSceneBootstrap：创建 API、状态、规则、资源、控制器和面板。
• GameSceneRuntimeAssembler：装配运行时 UI 和土地交互组件。
• GameScenePanelRouter：统一打开/关闭面板和弹窗入口。
• SceneHitRouter：管理主场景点击热区。
• FarmInteractionCoordinator：管理土地选择、长按、背包、菜单和作物提示。
• PlayerInventoryFacade：统一奖励、消耗、仓库刷新和货币变更。
• PlayerState：玩家快照唯一权威来源，收敛 token、等级、房屋、皮肤和土地列表等字段访问。

开发原则

• 先查原 H5 行为、资源 JSON、EXML、JS/PHP 逻辑，再写 Godot 实现。
• UI 必须对齐原版，优先使用 Egret 原素材。
• 网络请求必须走 ApiClient 和 scripts/services/*_api.gd。
• 状态变化优先走 scripts/state/ 和 Facade，再刷新 UI。
• 新面板放到 scripts/ui/panels/，不要堆到 game_scene.gd。
• 图集纹理优先走 TextureProvider、TextureRegionCatalog、AtlasTextureCache。
• 每次修改必须按影响面验证。

关键文档

• docs/godot-architecture-flow.md：整体模块化架构流程。
• docs/godot-architecture-refactor-progress.md：架构拆分进度。
• docs/godot-refactor-status-priority.md：P0/P1/P2 功能缺口和优先级。
• docs/godot-development-standards.md：Godot 开发规范和验证规则。
• docs/godot-migration-rebuild.md：Godot 重构方案。
• docs/godot-migration-progress.md：迁移进度。
• docs/ui-baseline/README.md：UI 基准截图说明。

当前主要缺口

P0 已完成。下一阶段主要是 P1：

• 好友搜索、申请、访问好友农场和好友互动。
• 世界玩法完整化：成就、竞技场、游乐园、战宠对战。
• 换肤/背景完整流程。
• 玩家信息面板。
• 活动面板逐页像素级对齐。
• 音频、FNT、全部原版动画和批量 EXML 辅助转换。

最近验证产物

docs/ui-baseline/smoke/
docs/ui-baseline/godot-architecture-refactor-main.png
docs/ui-baseline/godot-architecture-refactor-land-menu.png
docs/ui-baseline/godot-architecture-refactor-land-menu-closed.png
docs/ui-baseline/godot-architecture-refactor-main-menu.png
docs/ui-baseline/godot-architecture-refactor-meta.json