# Godot 重构进度与功能缺口优先级

更新时间：2026-05-12

## 依据

本清单基于当前本地代码和原 H5 参考核对，不按记忆推断。

- Godot 当前实现：`godot/FarmGodot/scripts/ui/game_scene.gd`
- Godot 服务层：`godot/FarmGodot/scripts/services/*.gd`
- Godot 配置层：`godot/FarmGodot/scripts/core/game_config_catalog.gd`
- 原 H5 面板通知：`muchang/home/web/game/js/main/00-runtime-and-notify.js`
- 原 H5 主场景入口：`muchang/home/web/game/js/main/03-game-ui-core.js`
- 原 H5 面板和中介：`muchang/home/web/game/js/main/05-config-and-panels.js`、`07-mediators.js`
- 原 H5 世界/宠物/游乐园/竞技：`13-world-features.js`、`15-battle-pet-full.js`、`16-amusement-park-full.js`、`17-sports-full.js`
- 最近验证截图：`docs/ui-baseline/godot-new2-final-*.png`

## 当前重构进度

### 已完成

- Godot 4.6.2 工程、Web 导出预设和 H5 本地预览流程。
- Egret 原资源同步到 `godot/FarmGodot/assets/egret/`。
- 自动登录：`13800000001 / 123456`。
- 后端协议：`ApiClient` 已按原 H5 `msg=<base64(JSON)>` 方式请求。
- 主农场第一版：
  - 顶部玩家信息、经验、金币、钻石、战力。
  - 农场背景、房屋、狗屋、围栏、土地、宠物牌。
  - 左侧活动入口、右下家园入口、左下世界入口。
  - 双指缩放土地场景，UI 不跟随缩放。
- 土地基础玩法：
  - 播种、收获、铲除、施肥、除虫、除草。
  - 成长倒计时、成熟自动刷新、成熟点击收获。
  - 种子包、化肥包、土地异常状态图标。
- 家园菜单第一版：
  - 商店、仓库、好友入口。
  - 商店购买、仓库出售、好友排行。
- 建筑和扩展：
  - 房屋升级面板和接口。
  - 土地扩建面板和接口。
  - 狗窝面板、狗粮喂养。
- 活动和系统入口：
  - 日志、系统公告、福利大厅、兑换金币。
  - 等级礼包、在线礼包、每日签到、宝箱、幸运转盘。
  - 宠物列表、宠物显示、宠物喂养、宠物参战。
  - 世界弹出菜单：投放、收获、喂养、去农场。
- 架构拆分：
  - `scripts/services/`：接口服务层已建立。
  - `scripts/state/`：玩家、农场、背包状态层已建立。
  - `scripts/domain/rules/`：土地动作、作物阶段、成本判断已建立。
  - `scripts/domain/mappers/`：农场和背包数据映射已建立。
  - `scripts/resources/`：图集区域和纹理缓存已建立。
  - `scripts/ui/hud/top_bar_view.gd`：顶部 HUD 渲染已迁出。
  - `scripts/ui/menus/`：主菜单和世界菜单控制器已迁出。
  - `scripts/ui/common/`：弹窗层、Toast、按钮动效公共逻辑已迁出。
  - `scripts/ui/farm/farm_viewport_controller.gd`：农场拖动视口、双指/滚轮缩放已迁出。
  - `scripts/ui/game_scene_runtime_assembler.gd`：HUD、菜单、弹窗、宠物展示、农场缩放、土地网格、土地菜单、背包、种植提示和 hit 路由装配已迁出。
  - `scripts/ui/game_scene_panel_router.gd`：所有面板入口、弹窗打开/关闭和仓库/好友入口状态已迁出。
  - `scripts/ui/game_scene_context.gd`：面板共享依赖和 legacy callback 兼容层已收敛。
  - `scripts/state/player_state.gd`：合并原玩家字段访问器，玩家快照只保留一个权威来源。
  - `scripts/ui/common/icon_texture_provider.gd`：物品、宠物、作物和房屋图标加载已集中缓存。

### 部分完成

- UI 对齐：主场景和大部分面板已能打开并使用原资源，但不是像素级一致。
- 动效：主菜单、世界菜单、土地菜单、弹窗有 Tween；仍未覆盖所有原版细节动效。
- 好友：只完成排行和列表；搜索、申请、访问好友家园、好友互动仍是占位提示。
- 世界功能：只完成菜单和信息型面板；游乐园、竞技场、成就领取、战宠对战还不是完整玩法。
- 福利大厅：VIP/卡数据显示和领取已接；购买周卡/月卡已接入充值下单入口，支付完成回调仍需海外平台 SDK。
- 兑换金币：兑换和记录已接；UI 仍是 Godot 第一版排版，不是原版完整皮肤。
- 资源系统：可读 Egret 图集 JSON 并缓存 `AtlasTexture`；没有批量生成 `.tres` 和 EXML 辅助转换工具。
- 架构：服务/状态/规则、公共 UI、运行时装配、面板路由、土地交互和主要面板已拆出；`game_scene.gd` 当前 957 行，已低于 1200 行目标，后续风险集中在旧面板 legacy callbacks。

### 明确未补齐

- 充值/支付：原 H5 有 `OPEN_PAY` 和 `pay/pay`；Godot 已接 Top Up、周卡/月卡购买入口和支付下单 URL 跳转，实际支付完成回调仍需接海外平台 SDK。
- 换肤/背景：原 H5 有 `OPEN_SKIN` 和 `farm/change-bg`；Godot 当前商店背景 tab 不是完整换肤流程。
- 玩家信息：原 H5 有 `OPEN_PLAYER_INFO`；Godot 当前头像点击没有完整角色信息面板。
- 好友搜索/申请/请求处理/赠送/互动/访问好友农场：Godot 当前大多是 toast 占位。
- 竞技场完整玩法：挑战列表、挑战、周奖励、领奖未补齐。
- 游乐园完整玩法：进入、翻牌/抽奖/奖励结算未补齐。
- 成就完整玩法：领取成就奖励未做完整交互。
- 战宠完整玩法：战斗详情、对战流程、战斗结果未补齐。
- 音频、FNT、全部原版动画、所有面板像素级对照未完成。

## P0：必须优先补齐

P0 是继续开发和第一版可玩闭环的阻断项。

| 项目 | 当前状态 | 依据 | 下一步 |
| --- | --- | --- | --- |
| 拆分 `game_scene.gd` | P0 完成：土地、背包、公共 UI、菜单、HUD、弹窗层、商店/仓库/好友/建筑/狗/活动/支付/福利/兑换/世界/签到/宝箱/转盘/宠物面板、启动装配、运行时装配、面板路由、hit 路由、土地交互协调、库存 Facade、玩家状态、场景上下文已拆成模块 | `wc -l godot/FarmGodot/scripts/ui/game_scene.gd` 当前低于 1200 行；新增 `GameSceneBootstrap`、`GameSceneRuntimeAssembler`、`GameScenePanelRouter`、`SceneHitRouter`、`FarmInteractionCoordinator`、`PlayerInventoryFacade`、`PlayerState`、`GameSceneContext` | P1 继续把旧面板从 legacy callbacks 迁到显式 Context 方法 |
| UI 像素级一致 | 功能入口已按原素材补齐并保留烟测截图；仍需逐页和 Egret 基准压差异 | `docs/ui-baseline/smoke/*.png` | 每个入口固定 Egret/Godot 对照截图，按主场景、土地、活动、家园面板逐页压差异 |
| 浇水 | 已完成 | 原 H5 `KICK_WATER -> farm/disease type=0`；`LandActionRules` 已接 `ACTION_WATER` | 干旱土地菜单显示浇水图标，执行 `farm/disease type=0`，刷新土地状态 |
| 土地升级 | 已完成第一版闭环 | 原 H5 `OPEN_LAND_UPGRADE -> farm/upgrade-land`；`BuildingApi.upgrade_land()` | 顶部 Land Up 打开原版布局面板，按土地等级/顺位取配置，校验等级/材料/前置土地，成功刷新土地 |
| 充值/支付入口 | 已完成第一版闭环 | 原 H5 `OPEN_PAY -> pay/pay`；Godot 新增 `PayApi` | Top Up 和福利卡购买打开充值面板，`pay/pay` 成功后 Web 端用 `JavaScriptBridge` 跳转支付 URL |
| 状态一致性 | P0 完成：奖励、消耗、仓库刷新、货币写入走 `PlayerInventoryFacade`，玩家快照字段统一走 `PlayerState` | 主场景内玩家字段不再依赖 `PlayerDataAccessor`，`PlayerInventoryFacade` 也改为引用 `PlayerState` | P1 把世界/好友等跨模块状态继续收敛到显式 State/Facade apply |
| 真实 Web 烟测流程 | 已完成 | `tools/smoke_godot_web.mjs` | 覆盖主场景、Top Up、Land Up、福利大厅、土地菜单、世界菜单、缩放；截图输出到 `docs/ui-baseline/smoke/` |

## P1：第一版完整度补齐

P1 是原版主要系统补齐项，不一定阻断农场主循环，但会影响“功能逻辑一致”。

| 项目 | 当前状态 | 依据 | 下一步 |
| --- | --- | --- | --- |
| 好友完整系统 | 排行和好友列表已接，搜索/申请/请求/访问/互动未接 | Godot 里 `好友搜索面板后续补齐`、`查看家园`、`互动` 为 toast | 补 `friend/find`、`friend/add`、`friend/get-respond-list`、`friend/respond-list`、`friend/respond`，再做好友农场场景 |
| 好友农场和互动 | 无 `SceneNotify.OPEN_OTHER_GAME` 对应完整场景 | 原 H5 `GO_OTHER_FARM`、`interaction/interaction` | 支持访问他人农场、放虫/放草/浇水/除虫/除草互动，区分自己和好友土地菜单 |
| 世界-成就 | 只展示列表，没有完整领取/分页/状态 | Godot 有 `fetch_achievements/claim_achievement`，UI 未完整绑定领取 | 补成就详情、领取按钮、领取后状态刷新 |
| 世界-竞技场 | 只展示基础数据和排行 | 原 H5 有 `arena/get-challenge-list`、`arena/challenge`、`arena/week-gift-list`、`arena/get-gift` | 补挑战列表、挑战流程、战斗结果、每周奖励 |
| 世界-游乐园 | 只展示次数和奖励配置 | 原 H5 有 `comm/enter-pleasure-ground`、`comm/pleasure-ground` | 补进入、玩法步骤、奖励结算和次数扣除 |
| 世界-战宠对战 | 宠物列表/喂养/参战已接，对战未接 | 原 H5 有 `pet/battle`、`pet/get-battle-info` | 补战宠对战入口、战斗详情、结果动画 |
| 换肤/背景 | 商店背景 tab 和换肤系统未闭环 | 原 H5 `OPEN_SKIN -> farm/change-bg` | 补 SkinPanel、已拥有背景列表、应用背景、购买背景后的状态刷新 |
| 玩家信息 | 未做完整角色信息面板 | 原 H5 `OPEN_PLAYER_INFO` | 头像点击打开角色资料，支持昵称/形象信息展示 |
| 活动面板细节 | 已能打开，部分逻辑和动效仍简化 | 宝箱、签到、福利、转盘等 Godot UI 为第一版 | 对照原皮肤补齐分页、倒计时、按钮状态、领奖动画、奖励弹窗 |
| 商店/仓库完整性 | 基础购买/出售已接 | 原 H5 商店含普通/神秘/背景，仓库含多分类 | 补完整分类、数量选择、使用道具、背景商品、不可售状态 |

## P2：质量、工具和发布能力

P2 不阻断第一版功能闭环，但影响长期效率、质量和海外发布。

| 项目 | 当前状态 | 下一步 |
| --- | --- | --- |
| EXML 辅助转换工具 | 未实现 | 做 EXML 坐标/九宫格/资源名提取工具，减少手写 UI 坐标 |
| Egret 图集批量 `.tres` 生成 | 局部使用运行时图集缓存 | 批量生成 Godot 可引用 AtlasTexture 或统一运行时缓存索引 |
| FNT/字体一致性 | 部分位图字和字体仍不完全一致 | 系统整理 FNT 解析和 Label 替换规则 |
| 音频系统 | 原资源已迁入，运行时播放未完整接入 | 补背景音乐、点击音效、奖励音效、开关设置 |
| 动效库 | 基础按钮/点击动效已抽到 `UiMotion`，部分面板和土地动效仍在各自模块 | 继续抽通用弹入、奖励飞字、面板切换动画 |
| 自动化测试 | 只有手动命令和截图脚本片段 | 增加 Godot check、Web 导出、Playwright 烟测的一键脚本 |
| CI/构建脚本 | 未固化 | 添加本地 `tools/export_web.sh` 或 Makefile，后续接 CI |
| 配置环境切换 | 后端地址写在 `project.godot` | 增加 dev/staging/prod 配置方案，避免手动改 base_url |
| 海外 SDK | 未接 | 支付、广告、统计、登录平台 SDK 通过 Web JavaScriptBridge 薄封装 |
| 代码清理 | 仍有重复/临时逻辑风险 | 清理重复 return、toast 占位、直接字典读写和未使用常量 |
| 文档同步 | 旧进度文档部分过期 | 用本文档作为当前优先级源，阶段完成后同步 `README.MD` 和迁移进度 |

## 建议执行顺序

1. 已完成：P0-2 浇水和土地升级，完成农场核心土地闭环。
2. 已完成：P0-3 充值/支付入口的可替换接口层，Top Up 和福利卡购买不再是占位。
3. 已完成：P0-4 Playwright Web 烟测脚本，导出后可固定跑主场景、土地、活动、世界、缩放。
4. 已完成：P0-1 `game_scene.gd` 深拆当前阶段，启动装配、hit 路由、土地交互、库存状态写入已迁出。
5. P1：按世界功能和好友功能拆独立模块，先做接口闭环，再压 UI。