# 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 `。 - 改网络：保存请求路径、请求参数、响应码、响应体摘要。 ## 9. 第三方工具规则 - 官方 API 能解决时不引第三方。 - 官方没有 GDScript 游戏单元测试框架，后续需要自动化测试时优先评估 GUT 9.6.0。 - 引入第三方前必须记录版本、来源、许可证、Godot 兼容版本和替代方案。