# Farm3 Godot H5 重构

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

## 当前状态

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

## 目录结构

```text
.
├── 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 版本：

```sh
godot --version
```

## 后端配置

后端地址在：

```text
godot/FarmGodot/project.godot
```

当前默认值：

```text
farm_game/api/base_url="http://127.0.0.1:18082/index.php?r="
farm_game/api/login_path="user/login"
```

自动登录账号在：

```text
godot/FarmGodot/scripts/bootstrap.gd
```

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

## 运行工程

从仓库根目录运行 Godot：

```sh
godot --path godot/FarmGodot
```

无界面导入检查：

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

## 导出 H5

从仓库根目录运行：

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

导出产物：

```text
godot/FarmGodot/build/web/
```

启动本地预览：

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

浏览器打开：

```text
http://127.0.0.1:8792/index.html
```

## 验证命令

安装 Node 依赖：

```sh
npm install
npx playwright install chromium
```

检查关键脚本：

```sh
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 规则和配置：

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

导出后跑 H5 smoke：

```sh
npm run smoke:godot:web
```

UI 图片对比：

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

## 当前架构

```text
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 辅助转换。

## 最近验证产物

```text
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
```