8. 贡献指南

欢迎为 Sync Engine 贡献代码！以下指南帮助你快速上手。

8.1. 目录结构

OpenSource/Sync/
├── include/sync/            # 核心头（sync::core 命名空间）
├── include/sync_godot/      # Godot 包装层头（godot:: 命名空间，19 个类）
├── src/core/                # 核心实现（静态库 build/）
├── src/godot/               # 包装层实现 + register_types.cpp（19 类唯一注册处）
├── doc_classes/             # 19 个类参考 XML
├── addons/sync/             # sync.gdextension + bin/（运行时分发物）
├── project/                 # demo Godot 项目
├── test/                    # 逻辑测试与基准测试
├── run_tests.py             # 纯 C++ 测试运行器
├── SConstruct               # 核心静态库构建
└── SConstruct.extension     # GDExtension 构建（编译 src/core + src/godot + DocData）

8.2. 编码规范

8.2.1. 语言与风格

  • 核心：C++17 标准，sync::core 命名空间（核心层）、 godot:: 命名空间（Godot 包装层）。

  • GDScript：demo 项目使用 GDScript，遵守 Godot 官方风格指南。

  • 保持一致：匹配现有代码的缩进风格、命名约定和注释密度。

  • 行尾：全仓库 LF 换行，禁止 CRLF。使用 .gitattributes 自动强制。

8.3. 如何新增类

Sync 是单一包，新增一个类只需改**两处** （无桥接 / 导出宏第三处）：

  1. 头文件：在 include/sync_godot/ 下创建类头（核心逻辑则 放 include/sync/）。

  2. 实现文件：在 src/godot/ 下创建 .cpp （核心实现在 src/core/）。

  3. 注册类型：在 src/godot/register_types.cpp 中调用 ClassDB::register_class<YourNewClass>()。

  4. 文档：在 doc_classes/ 下创建 YourNewClass.xml， 格式参考已有文件（Godot editor help 格式）。

重要

单包内所有类共享同一个 DLL 与注册上下文，包装类公开接口直接使用 具体 C++ 类型（如 Ref<T>），无需 Object* 签名或任何桥接。

8.4. 构建与测试

# 1) 核心静态库 + 逻辑测试
cd OpenSource/Sync
scons                          # debug
scons mode=release             # release
python run_tests.py            # 逻辑测试（必须全绿）

# 2) GDExtension（全 19 类 + DocData）
scons -f SConstruct.extension target=template_debug platform=windows
scons -f SConstruct.extension target=template_release platform=windows

# 3) demo 验证
godot --headless --quit-after 600 --path OpenSource/Sync/project

备注

run_tests.py 必须全绿才能提交。 Headless 验证务必加 --quit-after （秒数）兜底——demo 脚本若因编译 或运行错误未自行退出，headless 进程将永久挂死。

8.5. 文档

修改 Godot 类（增删方法/属性）后：

  • 更新 doc_classes/*.xml，格式遵循 Godot 编辑器帮助文档规范； 重新构建后 src/gen/doc_data.gen.cpp 自动再生。

  • 本 Sphinx 文档位于 OpenSource/docs/，修改后执行 make html （或 make.bat html）重建 HTML 并检查渲染结果。

  • 文档源文件统一使用 reStructuredText（.rst）格式。

8.6. PR 流程

  1. 创建 Feature 分支，命名自描述改动，如 feat/add-new-axis-type。

  2. 编写代码与测试，确保 run_tests.py 全绿。

  3. 更新文档：doc_classes/*.xml + Sphinx .rst 文件。

  4. 提交：commit message 使用中文 conventional 格式 （feat: / fix: / refactor: 等）。

  5. 发起 PR，描述改动内容与测试结果。

8.7. 许可证

Sync Engine 采用 MIT 许可证。贡献代码即表示你同意在该许可证下 分发你的贡献。