3.9 KiB
3.9 KiB
Godot 开发规范
1. 资料优先级
- Godot 4.6 官方文档和类参考。
- Godot 官方 GitHub Release、官方 godot-builds Release。
- 原项目本地资源、EXML、PHP/Yii 接口和数据库。
- 官方没有覆盖时，再查 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必须迁移为 GodotNinePatchRect，不能直接用普通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 兼容版本和替代方案。