3. 安装指南

3.1. 前置要求

软件	备注
Godot 4.x (4.3+)	Godot 引擎，编辑器或导出模板均可
C++17 编译器	MSVC / MinGW (Windows)、Clang (macOS)、 GCC (Linux)
SCons	构建系统（`pip install scons`）
git	获取 godot-cpp 子模块

3.2. 构建 Sync

Sync 是**单一包**：一个源码目录（OpenSource/Sync/）产出核心静态库与 GDExtension，无需按包顺序分步构建。

3.2.1. 1. 构建核心静态库并运行逻辑测试

cd OpenSource/Sync
scons                           # Debug 构建
scons mode=release              # Release 构建
python run_tests.py             # 逻辑测试（必须全绿）

产物输出到 build/。

小技巧

这一步不需要 godot-cpp。

3.2.2. 2. 构建 GDExtension

首次构建需要 godot-cpp 子模块（4.3 分支绑定）：

cd OpenSource/Sync
git submodule add -b 4.3 https://github.com/godotengine/godot-cpp.git
git -C godot-cpp submodule update --init

编译 GDExtension:

scons -f SConstruct.extension target=template_debug platform=windows
scons -f SConstruct.extension target=template_release platform=windows

产物输出到 addons/sync/bin/。

备注

上例用 Windows（platform=windows）。其他平台替换为 linux / macos / android。Android 需要 NDK。

3.3. 平台与目标

Sync 支持以下组合：

平台	Debug	Release
Windows (MSVC/MinGW)	`target=template_debug`	`target=template_release`
Linux (GCC/Clang)	`target=template_debug`	`target=template_release`
macOS (Clang)	`target=template_debug`	`target=template_release`
Android (NDK)	同上 + `platform=android`

3.4. 添加到 Godot 项目

复制 addons/ 目录 — 将 OpenSource/Sync/addons/sync/ 整个目录复制到你的 Godot 项目根目录下。

你的项目结构应类似:

your-project/
├── project.godot
└── addons/
    └── sync/              # sync.gdextension + bin/

登记扩展 — 打开一次 Godot 编辑器，让它扫描并登记新扩展。
检查 extension_list.cfg — 确认 .godot/extension_list.cfg 中已列出该扩展。如果编辑器未自动写入，手动补行:
```
res://addons/sync/sync.gdextension
```

3.5. 验证安装

用 headless 模式快速验证:

godot --headless --quit-after 200 --path your-project

如果扩展加载正常且初始化完成，进程会正常退出。出现错误时控制台会打印具体原因。

小技巧

--quit-after N 是兜底措施——如果项目脚本中有 get_tree().quit()，正常退出不会触达它。如果脚本编译/运行错误导致 quit 不可达， headless 进程会永久挂死。

3.6. 关于 junction / 符号链接

Sync 的 demo 项目使用**目录联接** （Windows mklink /J ）或 符号链接 （Linux/macOS ln -s ）将 addons/ 指向构建产物目录。这避免了重复复制二进制文件。

Windows：在管理员命令行中执行 mklink /J <link> <target>
Linux/macOS： ln -s <target> <link>

警告

Git Bash 的 ln -s 不支持目录符号链接，它会深拷贝整个目录。请使用原生 cmd / mklink （Windows）或原生 shell（Linux/macOS）。

3.7. 快速验证表

组件	验证方法
核心静态库	`python run_tests.py` （在 OpenSource/Sync/ 下）
GDExtension	启动含 `addons/sync` 的 Godot 项目，检查 19 个类可用
demo	`godot --headless --quit-after 600 --path OpenSource/Sync/project`

接下来，用几分钟上手 Sync 的核心用法。