85 lines
3.9 KiB
Markdown
85 lines
3.9 KiB
Markdown
# Godot 开发规范
|
||
|
||
## 1. 资料优先级
|
||
|
||
1. Godot 4.6 官方文档和类参考。
|
||
2. Godot 官方 GitHub Release、官方 godot-builds Release。
|
||
3. 原项目本地资源、EXML、PHP/Yii 接口和数据库。
|
||
4. 官方没有覆盖时，再查 GitHub/Godot Asset Library/社区资料，并在文档中记录来源。
|
||
|
||
## 2. 引擎和语言
|
||
|
||
- 固定使用 Godot 4.6.2 stable。
|
||
- 使用非 .NET 版本。
|
||
- 只写 GDScript，不引入 C#。
|
||
- Web 渲染路径使用 Compatibility。
|
||
- Web 导出默认单线程。
|
||
- Web 导出预设中 `vram_texture_compression/for_mobile` 默认保持 `false`，除非先启用并验证 ETC2/ASTC 导入设置。
|
||
|
||
## 3. 命名
|
||
|
||
遵循 Godot 官方 GDScript 风格指南：
|
||
|
||
- 文件名：`snake_case.gd`、`snake_case.tscn`。
|
||
- 类名：`PascalCase`。
|
||
- 函数和变量：`snake_case`。
|
||
- 常量：`ALL_CAPS`。
|
||
- 信号：过去式或事件语义，例如 `login_completed`、`inventory_changed`。
|
||
|
||
## 4. 代码规则
|
||
|
||
- 优先静态类型标注：`var name: String`、`func load_user() -> void`。
|
||
- 使用 `and`、`or`、`not`，不用 `&&`、`||`、`!`。
|
||
- 每个脚本只承担一个清晰职责。
|
||
- UI 节点脚本不直接拼后端 URL，不直接解析复杂业务规则。
|
||
- 网络请求统一从 `ApiClient` 发出。
|
||
- 配置项统一放 `project.godot` 或后续独立配置资源。
|
||
- 不在脚本里硬编码大量资源路径；临时路径必须在迁移文档里登记。
|
||
|
||
## 5. 场景规则
|
||
|
||
- UI 以完全一致为验收标准，不接受只“差不多”的重构。
|
||
- 每个页面必须先保存白鹭基准截图，再保存 Godot 同分辨率截图，并记录差异。
|
||
- 白鹭页面存在多个 canvas 时，实际游戏画布以最后一个 canvas 为准；旧登录页当前实测实际 canvas 为 `480 x 960`。
|
||
- 白鹭源 EXML 和编译后 `default.thm_*.js` 不一致时，以线上运行时编译皮肤和截图为准。
|
||
- 每个可复用 UI 面板都是独立 `.tscn`。
|
||
- 页面入口放在 `scenes/ui`。
|
||
- 运行入口只做场景装配，不写业务规则。
|
||
- 能用 `Control` 完成的 UI 不用 `Node2D`。
|
||
- Egret `scale9Grid` 必须迁移为 Godot `NinePatchRect`，不能直接用普通 `TextureRect` 拉伸。
|
||
- 使用 640 x 960 作为当前登录页基准，后续如确认线上实际为 640 x 1136，再统一调整。
|
||
|
||
## 6. 资源规则
|
||
|
||
- Egret 原资源先保存在 `assets/egret` 作为迁移输入。
|
||
- Godot 可运行资源逐步转入 Godot 原生资源格式。
|
||
- 图集转换要保留原 Egret 资源名，避免 UI 绑定丢失。
|
||
- 字体授权未确认前，不把字体作为最终发布依赖。
|
||
|
||
## 7. Web 规则
|
||
|
||
- Web 构建必须使用 `index.html` 作为入口文件名。
|
||
- Web 导出的 HTML shell 必须保持旧 H5 的可见容器规则；当前登录页是 `max-width: 480px; height: 100vh; background: #000`。
|
||
- 所有 HTTP 接口必须支持 HTTPS 和 CORS。
|
||
- 不使用原生 TCP/UDP。
|
||
- 需要浏览器能力时优先查 `JavaScriptBridge` 官方文档。
|
||
- 广告、统计、平台 SDK 通过 JavaScriptBridge 做薄封装，不污染核心玩法代码。
|
||
|
||
## 8. 验证规则
|
||
|
||
每次修改至少做对应验证：
|
||
|
||
- 改 GDScript：执行 `--check-only --script`。
|
||
- 改资源或场景：执行 `--import --quit`。
|
||
- 改 Web/平台相关：执行 Web 导出。
|
||
- 改 Web 导出预设：同时验证 `index.html`、`index.wasm`、`index.pck` 能通过本地 HTTP 服务访问。
|
||
- 改 UI：用 Godot 或浏览器截图和 Egret 基准截图对比。
|
||
- UI 对比命令：`NODE_PATH=/tmp/farm3-playwright/node_modules node tools/compare_ui_baseline.mjs <egret.png> <godot.png> <diff.png>`。
|
||
- 改网络：保存请求路径、请求参数、响应码、响应体摘要。
|
||
|
||
## 9. 第三方工具规则
|
||
|
||
- 官方 API 能解决时不引第三方。
|
||
- 官方没有 GDScript 游戏单元测试框架，后续需要自动化测试时优先评估 GUT 9.6.0。
|
||
- 引入第三方前必须记录版本、来源、许可证、Godot 兼容版本和替代方案。
|