# 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. 目录结构 ```text 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