hy-farm/docs/godot-migration-rebuild.md

Godot H5 重构文档

1. 结论

本项目从白鹭/Egret H5 客户端重构为 Godot 4.6.2 + GDScript 客户端。当前目标是海外 H5，不接国内小游戏生态，因此优先选择 Godot Web 单线程导出，避免 Unity Web 学习成本和 Cocos Creator 生态迁移成本。

UI 验收标准是完全一致：关键页面必须以原白鹭版本截图为基准做像素级对照。只跑通功能但视觉不一致，不能算该页面完成。

已确认的最新稳定版本：

• Godot 最新稳定版：4.6.2-stable，GitHub Release 发布于 2026-04-01。
• 本机安装版本：4.6.2.stable.official.71f334935。
• 工程路径：godot/FarmGodot。

2. 原项目事实

当前客户端事实来自仓库，不做猜测：

• 原客户端是白鹭/Egret H5。
• 主要资源目录：muchang/home/web/game/resource，这是当前新版解密 HTML 的资源基准。
• UI 皮肤：resource/skins/**/*.exml。
• 资源清单：default.res.json、default.thm.json。
• 编译逻辑：muchang/farmer/js/main.min_77d7299f.js。
• 未发现完整 TypeScript 源码、source map、egretProperties.json。

因此这不是自动转换工程，而是以资源、EXML、运行表现、后端接口为规格重新实现客户端。

3. 第一版范围

第一版只追求最短闭环：

1. Godot 工程能被 Godot 4.6.2 打开和导入。
2. Web/H5 导出模板可用。
3. 登录界面按 LoginSceneSkin.exml 和白鹭截图做完全一致复刻。
4. 解析 Egret default.res.json。
5. 表单校验通过。
6. 配置后端地址后，可以通过 Godot HTTPRequest 调登录接口。
7. 登录后进入空主场景，再扩展土地、作物、顶部资源栏。

4. 目录结构

godot/FarmGodot/
  project.godot
  export_presets.cfg
  assets/
    egret/
      default.res.json
      default.thm.json
      assets/
      config/
      fonts/
      skins/
      common/
      preloading/
      login/
      common/
      preloading/
  scenes/
    bootstrap.tscn
    ui/login_scene.tscn
  scripts/
    bootstrap.gd
    core/
    services/
    ui/

5. 官方 API 依据

开发时优先使用 Godot 官方文档：

• Godot 4.6.2 Release：https://github.com/godotengine/godot/releases/tag/4.6.2-stable
• Godot Web 导出：https://docs.godotengine.org/en/4.6/tutorials/export/exporting_for_web.html
• Godot 自定义 HTML shell：https://docs.godotengine.org/en/4.6/tutorials/platform/web/customizing_html5_shell.html
• GDScript 风格指南：https://docs.godotengine.org/en/4.6/tutorials/scripting/gdscript/gdscript_styleguide.html
• Nodes and Scenes：https://docs.godotengine.org/en/4.6/getting_started/step_by_step/nodes_and_scenes.html
• 多分辨率和 Stretch：https://docs.godotengine.org/en/stable/tutorials/rendering/multiple_resolutions.html
• HTTPRequest：https://docs.godotengine.org/en/4.6/tutorials/networking/http_request_class.html
• JavaScriptBridge：https://docs.godotengine.org/en/4.6/tutorials/platform/web/javascript_bridge.html
• TextureRect：https://docs.godotengine.org/en/4.6/classes/class_texturerect.html
• TextureButton：https://docs.godotengine.org/en/4.6/classes/class_texturebutton.html
• ScrollContainer：https://docs.godotengine.org/en/4.6/classes/class_scrollcontainer.html
• NinePatchRect：https://docs.godotengine.org/en/4.6/classes/class_ninepatchrect.html
• Control：https://docs.godotengine.org/en/4.6/classes/class_control.html
• AtlasTexture：https://docs.godotengine.org/en/4.6/classes/class_atlastexture.html
• Timer：https://docs.godotengine.org/en/4.6/classes/class_timer.html
• FileAccess：https://docs.godotengine.org/en/4.6/classes/class_fileaccess.html
• JSON：https://docs.godotengine.org/en/4.6/classes/class_json.html

官方没有覆盖到的自动化测试框架，后续优先评估 GitHub/Godot Asset Library 的 GUT。当前查到 GUT 9.6.0 支持 Godot 4.6.x：https://github.com/bitwes/Gut

6. Web/H5 约束

根据官方 Web 导出文档：

• Godot 4 Web 需要浏览器支持 WebAssembly 和 WebGL 2.0。
• Godot 4 C# 不能导出 Web，因此本工程只使用 GDScript。
• Web 目标只能使用 Compatibility 渲染路径，不能使用 Forward+/Mobile。
• Web HTTP 请求受浏览器同源策略和 CORS 限制。
• WebSocket 客户端可用，但不能依赖原生 TCP/UDP socket。
• 默认使用单线程 Web 导出，避免 SharedArrayBuffer 和 cross-origin isolation 约束。

7. 迁移策略

UI

• EXML 作为规格，不直接当运行时格式。
• 如果 EXML 和 default.thm_*.js 编译结果不同，以旧 H5 实际运行截图和编译结果为准。
• 第一阶段手工复刻关键页面：登录、主场景、顶部资源栏、农场视图。
• 页面完成标准是白鹭截图和 Godot 截图在同分辨率下像素级对齐，任何肉眼可见差异都记录为未完成。
• 使用浏览器截图对比时，必须记录页面截图、实际 canvas 截图、元数据和 diff 图。
• 后续再写 EXML 扫描/辅助转换工具，不追求 100% 自动转换。
• Godot UI 使用 Control、TextureRect、NinePatchRect、Label、LineEdit、Button、TextureButton、ScrollContainer。

资源

• 原版新版素材完整同步到 godot/FarmGodot/assets/egret/，相对路径和 muchang/home/web/game/resource/ 保持一致。
• default.res.json 用 GameConfigCatalog 和后续 Egret 资源解析器读取。
• 普通图片先作为 Godot Texture2D 直接导入。
• Egret 图集 png + json 后续转为 Godot 可引用的 AtlasTexture 资源。
• 字体、FNT、音频原始文件已迁入；运行时按页面需要逐步接入位图字体、音效和动效。

网络

• HTTP 统一走 ApiClient，内部使用 Godot HTTPRequest。
• 配置项放在 project.godot 的 farm_game/api/base_url。
• Web 环境必须先验证 CORS。
• 旧 PHP/Yii 接口先不改，Godot 端适配请求和响应。

架构

• scripts/services 放网络、配置、账号等服务。
• scripts/core 放无场景依赖的纯逻辑。
• scripts/ui 放界面脚本。
• 场景负责组合节点，业务逻辑放脚本，数据模型不要写进 UI 节点。

8. 土地交互规范

土地交互以旧白鹭客户端和后端接口为准，不凭空设计新流程。

原版菜单规则

• 空地：普通点击显示播种菜单。
• 成长中：普通点击显示铲除、施肥；如果有虫害显示除虫；如果有草害显示除草。
• 成熟：普通点击显示收割。
• 已收割或枯萎：普通点击显示铲除。
• 倒计时：按旧客户端长按行为显示 PlantCdTip，不能占用普通点击菜单。

接口映射

• 播种：farm/sow-seeds
• 收获：farm/gather-crop
• 铲除：farm/clear-land
• 施肥：farm/fertilize
• 除虫/除草：farm/disease，虫害类型 1，草害类型 2
• 种子、化肥、作物配置：game_config.json
• 背包数据：store-house

Godot 实现约束

• 土地状态按钮继续由 Control/Button 覆盖土地热区，不改变底层贴图布局。
• 圆形操作菜单沿用旧版菜单贴图和相对位置，不新增解释性文案。
• 作物阶段、种子名称、化肥图标和阶段时间从 GameConfigCatalog 读取。
• game_config.json 通过 Web export include filter 保持原始文件导出；运行时用 FileAccess 和 JSON 读取。
• 长按倒计时使用 Timer 识别，进度条和面板使用旧版图集区域与 NinePatchRect。
• 每个会改后端状态的操作成功后，只刷新当前土地和必要的本地玩家资源，不做整页重载。

9. 验证标准

每个阶段必须验证：

• Godot 能导入工程：godot --headless --path godot/FarmGodot --import --quit
• GDScript 语法能检查：godot --headless --path godot/FarmGodot --check-only --script <script>
• Web 能导出：godot --headless --path godot/FarmGodot --export-release Web build/web/index.html
• 浏览器可打开构建产物。
• 与 Egret 版本对照截图，逐页修正布局。
• 涉及接口的功能必须用真实后端账号验证 HTTP 状态和业务状态，并在测试后恢复测试数据。
• UI 像素对比：NODE_PATH=/tmp/farm3-playwright/node_modules node tools/compare_ui_baseline.mjs docs/ui-baseline/egret-login-page.png docs/ui-baseline/godot-login-page.png docs/ui-baseline/login-page-diff.png

10. 近期开发顺序

1. 把登录页像素差异从当前 1.8239% 压到可验收。
2. 对照主农场截图继续压 UI 差异：顶部 FNT、资源文字对齐、左侧入口、世界/家园入口。
3. 建立玩家数据模型，保存 token、玩家基础信息、土地列表、背包摘要。
4. 补齐土地剩余交互：浇水、扩建、未开垦土地购买/开放。
5. 建立更多页面的白鹭截图和 Godot 截图对比流程。