232 lines
7.7 KiB
Markdown
232 lines
7.7 KiB
Markdown
# 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
|
||
```
|