188 lines
8.6 KiB
Markdown
188 lines
8.6 KiB
Markdown
# 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 <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 截图对比流程。
|